doc: wip

be6ba436 · Dimitris Lampridis · bc19c9e1 · be6ba436 · be6ba436 · be6ba436
Commit be6ba436 authored Jul 04, 2019 by Dimitris Lampridis
Hide whitespace changes
Inline Side-by-side

Showing with 48 additions and 40 deletions

basic_concepts.rst doc/basic_concepts.rst +5 -6

introduction.rst doc/introduction.rst +8 -5

usage.rst doc/usage.rst +35 -29

No files found.
--- a/doc/basic_concepts.rst
+++ b/doc/basic_concepts.rst
@@ -211,7 +211,7 @@ Attributes can be attached to a :ref:`rep_cap`, or they can be "global" (apply t
   functions to get/set a global Attribute, a special :ref:`rep_cap_id` must be passed to the
   function (:c:macro:`WRTD_GLOBAL_REP_CAP_ID`) as the Selector.
-Please refer to the :ref:`api_attr_list` and the :ref:`api_attr` for more details.
+Please refer to the :ref:`api_attr` for more details.
 .. _rule:
@@ -250,7 +250,7 @@ in :numref:`fig-wrtd-rule-tx`.
 .. hint:: There are actually more :ref:`Attributes <attribute>` than the ones shown in
          :numref:`fig-wrtd-rule-rx` and :numref:`fig-wrtd-rule-tx`. Please refer to the
-          :ref:`api_attr_list` for the complete list, as well as an explanation of each
+          :ref:`api_attr` for the complete list, as well as an explanation of each
          :ref:`Attribute`.
 .. _alarm:
@@ -284,7 +284,7 @@ triggered, following the process depicted in :numref:`fig-wrtd-alarm`.
   Anatomy of an Alarm
 .. hint:: There are actually more :ref:`Attributes <attribute>` than the ones shown in
-          :numref:`fig-wrtd-alarm`. Please refer to the :ref:`api_attr_list` for the complete list,
+          :numref:`fig-wrtd-alarm`. Please refer to the :ref:`api_attr` for the complete list,
          as well as an explanation of each :ref:`Attribute`.
 .. _application:
@@ -303,9 +303,8 @@ Applications. They can only get their (read-only) :ref:`Attributes <attribute>`
 information regarding firmware version, number and direction of :ref:`Local Channels
 <local_channel>`, etc.
-Please refer to the :ref:`api_attr_list` for the complete list of Application-related
+Please refer to the :ref:`api_attr` for the complete list of Application-related :ref:`Attributes
-:ref:`Attributes <attribute>`. The :ref:`rep_cap_id` of each Application can be retrieved using the
+<attribute>`. The :ref:`rep_cap_id` of each Application can be retrieved using the :ref:`api_app`.
-:ref:`api_app`.
 .. _LXI Core Specification: http://www.lxistandard.org/members/Adopted%20Specifications/Latest%20Version%20of%20Standards_/LXI%20Standard%201.5%20Specifications/LXI%20Device%20Specification%20v1_5_01.pdf

--- a/doc/introduction.rst
+++ b/doc/introduction.rst
@@ -86,11 +86,14 @@ to the `IVI-3.15 IviLxiSync Specification`_.
 Since the LXI event exchanging mechanism is conceptually very close to WRTD, it was decided to
 design WRTD to be as close to LXI as possible. In particular:
-* WRTD uses the same :ref:`Message format <message>`. This already allows LXI and WRTD devices on
+* WRTD uses the same Message format. This already allows LXI and WRTD devices on the same network to
-  the same network to exchange events, even if the API for programming these events is different.
+  exchange events, even if the API for programming these events is different.
-* the :ref:`WRTD library API <clib>` mimics that of an IVI driver, with a strong influence from the
+* the WRTD library API mimics that of an IVI driver, with a strong influence from the `IVI-3.15
-  `IVI-3.15 IviLxiSync Specification`_, even if several of the :ref:`Repeated Capabilities
+  IviLxiSync Specification`_, even if several of the Repeated Capabilities and Attributes are
-  <rep_cap>` and :ref:`Attributes <attribute>` are different.
+  different.
+.. hint:: Do not worry if you do not understand some of the terminology yet. It will be explained in
+          :numref:`basic_concepts`.
 In the future, and with `White Rabbit being standardized within the next release of IEEE-1588
 <https://www.ohwr.org/project/wr-std/wikis/home>`_, it is foreseen to try to merge WRTD with

--- a/doc/usage.rst
+++ b/doc/usage.rst
@@ -9,29 +9,26 @@ Usage
 WRTD Library
 ============
-WRTD Timestamps
+.. _api_error:
---------------
-.. doxygenstruct:: wrtd_tstamp
-                   :members:
-WRTD Error Codes
+Error Handling API
----------------
+------------------
-.. doxygenenum:: wrtd_status
+Error Codes
+++++++++++
-.. _api_attr_list:
+.. doxygenenum:: wrtd_status
-List of Attributes
+Functions
------------------
+++++++++
-.. doxygenenum:: wrtd_attr
-.. doxygendefine:: WRTD_GLOBAL_REP_CAP_ID
+.. doxygenfunction:: wrtd_get_error
+.. doxygenfunction:: wrtd_error_message
-WRTD API
+.. _api_init:
--------
-Initialisation
+Initialisation API
-++++++++++++++
+------------------
 .. doxygenfunction:: wrtd_init
 .. doxygenfunction:: wrtd_close
@@ -40,7 +37,20 @@ Initialisation
 .. _api_attr:
 Attribute Handling API
-++++++++++++++++++++++
+----------------------
+Attributes
++++++++++
+.. doxygenenum:: wrtd_attr
+.. doxygendefine:: WRTD_GLOBAL_REP_CAP_ID
+Functions
+++++++++
+.. doxygenstruct:: wrtd_tstamp
+                   :members:
 .. doxygenfunction:: wrtd_set_attr_bool
 .. doxygenfunction:: wrtd_get_attr_bool
@@ -51,14 +61,10 @@ Attribute Handling API
 .. doxygenfunction:: wrtd_set_attr_tstamp
 .. doxygenfunction:: wrtd_get_attr_tstamp
-Error Handling
+.. _api_log:
-++++++++++++++
-.. doxygenfunction:: wrtd_get_error
+Event Logging API
-.. doxygenfunction:: wrtd_error_message
+-----------------
-Event Log
-+++++++++
 .. doxygendefine:: WRTD_LOG_ENTRY_SIZE
@@ -68,7 +74,7 @@ Event Log
 .. _api_alarm:
 Alarms API
-++++++++++
+----------
 .. doxygenfunction:: wrtd_add_alarm
 .. doxygenfunction:: wrtd_disable_all_alarms
@@ -79,7 +85,7 @@ Alarms API
 .. _api_rule:
 Rules API
-+++++++++
+---------
 .. doxygenfunction:: wrtd_add_rule
 .. doxygenfunction:: wrtd_disable_all_rules
@@ -91,16 +97,16 @@ Rules API
 .. _api_app:
 Applications API
-++++++++++++++++
+----------------
 .. doxygenfunction:: wrtd_get_fw_name
 .. _pywrap:
 Python Library
--------------
+==============
 .. _tools:
 Tools
-----
+=====