Cleanup the auto-converted northbound doc a little

doc/developer/northbound/advanced-topics.rst

@@ -1,3 +1,11 @@
+Advanced Topics
+===============
+
+.. contents:: Table of contents
+    :local:
+    :backlinks: entry
+    :depth: 1
+
 Auto-generated CLI commands
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -34,13 +42,16 @@ CLI on a separate program
 
 The flexible design of the northbound architecture opens the door to
 move the CLI to a separate program in the long-term future. Some
-advantages of doing so would be: \* Treat the CLI as just another
-northbound client, instead of having CLI commands embedded in the
-binaries of all FRR daemons. \* Improved robustness: bugs in CLI
-commands (e.g. null-pointer dereferences) or in the CLI code itself
-wouldn’t affect the FRR daemons. \* Foster innovation by allowing other
-CLI programs to be implemented, possibly using higher level programming
-languages.
+advantages of doing so would be:
+
+* Treat the CLI as just another northbound client, instead of having CLI
+  commands embedded in the binaries of all FRR daemons.
+
+* Improved robustness: bugs in CLI commands (e.g. null-pointer dereferences) or
+  in the CLI code itself wouldn’t affect the FRR daemons.
+
+* Foster innovation by allowing other CLI programs to be implemented, possibly
+  using higher level programming languages.
 
 The problem, however, is that the northbound retrofitting process will
 convert only the CLI configuration commands and EXEC commands in a first
@@ -232,40 +243,42 @@ vtysh support
 As explained in the [[Transactional CLI]] page, all commands introduced
 by the transactional CLI are not yet available in *vtysh*. This needs to
 be addressed in the short term future. Some challenges for doing that
-work include: \* How to display configurations (running, candidates and
-rollbacks) in a more clever way? The implementation of the
-``show running-config`` command in *vtysh* is not something that should
-be followed as an example. A better idea would be to fetch the desired
-configuration from all daemons (encoded in JSON for example), merge them
-all into a single ``lyd_node`` variable and then display the combined
-configurations from this variable (the configuration merges would
-transparently take care of combining the shared configuration objects).
-In order to be able to manipulate the JSON configurations, *vtysh* will
-need to load the YANG modules from all daemons at startup (this might
-have a minimal impact on startup time). The only issue with this
-approach is that the ``cli_show()`` callbacks from all daemons are
-embedded in their binaries and thus not accessible externally. It might
-be necessary to compile these callbacks on a separate shared library so
-that they are accessible to *vtysh* too. Other than that, displaying the
-combined configurations in the JSON/XML formats should be
-straightforward. \* With the current design, transaction IDs are
-per-daemon and not global across all FRR daemons. This means that the
-same transaction ID can represent different transactions on different
-daemons. Given this observation, how to implement the
-``rollback configuration`` command in *vtysh*? The easy solution would
-be to add a ``daemon WORD`` argument to specify the context of the
-rollback, but per-daemon rollbacks would certainly be confusing and
-convoluted to end users. A better idea would be to attack the root of
-the problem: change configuration transactions to be global instead of
-being per-daemon. This involves a bigger change in the northbound
-architecture, and would have implications on how transactions are stored
-in the SQL database (daemon-specific and shared configuration objects
-would need to have their own tables or columns). \* Loading
-configuration files in the JSON or XML formats will be tricky, as
-*vtysh* will need to know which sections of the configuration should be
-sent to which daemons. *vtysh* will either need to fetch the YANG
-modules implemented by all daemons at runtime or obtain this information
-at compile-time somehow.
+work include:
+
+* How to display configurations (running, candidates and rollbacks) in a more
+  clever way? The implementation of the ``show running-config`` command in
+  *vtysh* is not something that should be followed as an example. A better idea
+  would be to fetch the desired configuration from all daemons (encoded in JSON
+  for example), merge them all into a single ``lyd_node`` variable and then
+  display the combined configurations from this variable (the configuration
+  merges would transparently take care of combining the shared configuration
+  objects). In order to be able to manipulate the JSON configurations, *vtysh*
+  will need to load the YANG modules from all daemons at startup (this might
+  have a minimal impact on startup time). The only issue with this approach is
+  that the ``cli_show()`` callbacks from all daemons are embedded in their
+  binaries and thus not accessible externally. It might be necessary to compile
+  these callbacks on a separate shared library so that they are accessible to
+  *vtysh* too. Other than that, displaying the combined configurations in the
+  JSON/XML formats should be straightforward.
+
+* With the current design, transaction IDs are per-daemon and not global across
+  all FRR daemons. This means that the same transaction ID can represent
+  different transactions on different daemons. Given this observation, how to
+  implement the ``rollback configuration`` command in *vtysh*? The easy solution
+  would be to add a ``daemon WORD`` argument to specify the context of the
+  rollback, but per-daemon rollbacks would certainly be confusing and convoluted
+  to end users. A better idea would be to attack the root of the problem: change
+  configuration transactions to be global instead of being per-daemon. This
+  involves a bigger change in the northbound architecture, and would have
+  implications on how transactions are stored in the SQL database
+  (daemon-specific and shared configuration objects would need to have their own
+  tables or columns).
+
+* Loading configuration files in the JSON or XML formats will be tricky, as
+  *vtysh* will need to know which sections of the configuration should be sent
+  to which daemons. *vtysh* will either need to fetch the YANG modules
+  implemented by all daemons at runtime or obtain this information at
+  compile-time somehow.
 
 Detecting type mismatches at compile-time
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/developer/northbound/architecture.rst

@@ -1,3 +1,6 @@
+Architecture
+============
+
 Introduction
 ------------
 
@@ -42,30 +45,34 @@ and
 `CoAP <https://www.ietf.org/archive/id/draft-vanderstok-core-comi-11.txt>`__.
 
 In addition to being management-protocol independent, some other
-advantages of using YANG in FRR are listed below: \* Have a formal
-contract between FRR and application developers (management clients). A
-management client that has access to the FRR YANG models knows about all
-existing configuration options available for use. This information can
-be used to auto-generate user-friendly interfaces like Web-UIs, custom
-CLIs and even code bindings for several different programming languages.
-Using `PyangBind <https://github.com/robshakir/pyangbind>`__, for
-example, it’s possible to generate Python class hierarchies from YANG
-models and use these classes to instantiate objects that mirror the
-structure of the YANG modules and can be serialized/deserialized using
-different encoding formats. \* Support different encoding formats for
-instance data. Currently only JSON and XML are supported, but
-`GPB <https://developers.google.com/protocol-buffers/>`__ and
-`CBOR <http://cbor.io/>`__ are other viable options in the long term.
-Additional encoding formats can be implemented in the *libyang* library
-for optimal performance, or externally by translating data to/from one
-of the supported formats (with a performance penalty). \* Have a formal
-mechanism to introduce backward-incompatible changes based on `semantic
-versioning <http://www.openconfig.net/docs/semver/>`__ (not part of the
-YANG standard, which allows backward-compatible module updates only). \*
-Provide seamless support to the industry-standard NETCONF/RESTCONF
-protocols as alternative management APIs. If FRR configuration/state
-data is modeled using YANG, supporting YANG-based protocols like NETCONF
-and RESTCONF is much easier.
+advantages of using YANG in FRR are listed below:
+
+* Have a formal contract between FRR and application developers (management
+  clients). A management client that has access to the FRR YANG models knows
+  about all existing configuration options available for use. This information
+  can be used to auto-generate user-friendly interfaces like Web-UIs, custom
+  CLIs and even code bindings for several different programming languages. Using
+  `PyangBind <https://github.com/robshakir/pyangbind>`__, for example, it’s
+  possible to generate Python class hierarchies from YANG models and use these
+  classes to instantiate objects that mirror the structure of the YANG modules
+  and can be serialized/deserialized using different encoding formats.
+
+* Support different encoding formats for instance data. Currently only JSON and
+  XML are supported, but `GPB
+  <https://developers.google.com/protocol-buffers/>`__ and `CBOR
+  <http://cbor.io/>`__ are other viable options in the long term. Additional
+  encoding formats can be implemented in the *libyang* library for optimal
+  performance, or externally by translating data to/from one of the supported
+  formats (with a performance penalty).
+
+* Have a formal mechanism to introduce backward-incompatible changes based on
+  `semantic versioning <http://www.openconfig.net/docs/semver/>`__ (not part of
+  the YANG standard, which allows backward-compatible module updates only).
+
+* Provide seamless support to the industry-standard NETCONF/RESTCONF protocols
+  as alternative management APIs. If FRR configuration/state data is modeled
+  using YANG, supporting YANG-based protocols like NETCONF and RESTCONF is much
+  easier.
 
 As important as shifting to a model-driven management paradigm, the new
 northbound architecture also introduces the concept of configuration

doc/developer/northbound/demos.rst

@@ -1,3 +1,6 @@
+Demos
+=====
+
 Transactional CLI
 -----------------
 

doc/developer/northbound/links.rst

@@ -1,3 +1,6 @@
+Links
+=====
+
 RFCs
 ~~~~
 

doc/developer/northbound/northbound.rst

@@ -11,11 +11,11 @@ Northbound API
    transactional-cli
    retrofitting-configuration-commands
    operational-data-rpcs-and-notifications
-   plugins-sysrepo
    advanced-topics
    yang-tools
    yang-module-translator
    demos
    links
+   plugins-sysrepo
    ppr-basic-test-topology
    ppr-mpls-basic-test-topology

doc/developer/northbound/operational-data-rpcs-and-notifications.rst

@@ -1,3 +1,11 @@
+Operational Data, RPCs and Notifications
+========================================
+
+.. contents:: Table of contents
+    :local:
+    :backlinks: entry
+    :depth: 1
+
 Operational data
 ~~~~~~~~~~~~~~~~
 
@@ -330,10 +338,12 @@ CLI can take too long, potentially long enough to the point of
 triggering some protocol timeouts and bringing sessions down.
 
 To avoid this kind of problem, northbound clients are encouraged to do
-one of the following: \* Create a separate pthread for handling requests
-to fetch operational data. \* Iterate over YANG lists and leaf-lists
-asynchronously, returning a maximum number of elements per time instead
-of returning all elements in one shot.
+one of the following:
+
+* Create a separate pthread for handling requests to fetch operational data.
+
+* Iterate over YANG lists and leaf-lists asynchronously, returning a maximum
+  number of elements per time instead of returning all elements in one shot.
 
 In order to handle both cases correctly, the ``get_next`` callbacks need
 to use locks to prevent the YANG lists from being modified while they

doc/developer/northbound/plugins-sysrepo.rst

@@ -1,3 +1,6 @@
+Plugins Sysrepo (old)
+=====================
+
 Installation
 ------------
 

doc/developer/northbound/ppr-basic-test-topology.rst

@@ -1,15 +1,10 @@
-Table of Contents
-~~~~~~~~~~~~~~~~~
+IS-IS PPR Basic
+===============
 
--  `Software <#software>`__
--  `Topology <#topology>`__
--  `Configuration <#configuration>`__
-
-   -  `CLI <#configuration-cli>`__
-   -  `YANG <#configuration-yang>`__
-
--  `Verification - Control Plane <#verification-cplane>`__
--  `Verification - Forwarding Plane <#verification-fplane>`__
+.. contents:: Table of contents
+    :local:
+    :backlinks: entry
+    :depth: 2
 
 Software
 ~~~~~~~~

doc/developer/northbound/ppr-mpls-basic-test-topology.rst

@@ -1,15 +1,10 @@
-Table of Contents
-~~~~~~~~~~~~~~~~~
+IS-IS PPR Basic MPLS
+====================
 
--  `Software <#software>`__
--  `Topology <#topology>`__
--  `Configuration <#configuration>`__
-
-   -  `CLI <#configuration-cli>`__
-   -  `YANG <#configuration-yang>`__
-
--  `Verification - Control Plane <#verification-cplane>`__
--  `Verification - Forwarding Plane <#verification-fplane>`__
+.. contents:: Table of contents
+    :local:
+    :backlinks: entry
+    :depth: 2
 
 Software
 ~~~~~~~~