diff options
Diffstat (limited to 'doc/developer/workflow.rst')
| -rw-r--r-- | doc/developer/workflow.rst | 86 |
1 files changed, 62 insertions, 24 deletions
diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst index f6519ea8f6..f025c47bb4 100644 --- a/doc/developer/workflow.rst +++ b/doc/developer/workflow.rst @@ -668,7 +668,7 @@ AddressSanitizer instrumentation and run through a series of tests to look for any results. Testing your own code with this tool before submission is encouraged. You can enable it by passing:: - + --enable-address-sanitizer to ``configure``. @@ -678,7 +678,7 @@ ThreadSanitizer detecting data races. If you are working on or around multithreaded code, extensive testing with this instrumtation enabled is *highly* recommended. You can enable it by passing:: - + --enable-thread-sanitizer to ``configure``. @@ -687,7 +687,7 @@ MemorySanitizer Similar to AddressSanitizer, this tool provides runtime instrumentation for detecting use of uninitialized heap memory. Testing your own code with this tool before submission is encouraged. You can enable it by passing:: - + --enable-memory-sanitizer to ``configure``. @@ -775,27 +775,33 @@ FRR uses Sphinx+RST as its documentation system. The document you are currently reading was generated by Sphinx from RST source in :file:`doc/developer/workflow.rst`. The documentation is structured as follows: -+-----------------------+--------------------------------------------------------------+ -| Directory | Contents | -+=======================+==============================================================+ -| :file:`doc/user` | User documentation; configuration guides; protocol overviews | -+-----------------------+--------------------------------------------------------------+ -| :file:`doc/developer` | Developer's documentation; API specs; datastructures; | -| | architecture overviews; project management procedure | -+-----------------------+--------------------------------------------------------------+ -| :file:`doc/manpages` | Source for manpages | -+-----------------------+--------------------------------------------------------------+ -| :file:`doc/figures` | Images and diagrams | -+-----------------------+--------------------------------------------------------------+ - -Each of these directories, with the exception of :file:`doc/figures`, contains -a Sphinx-generated Makefile and configuration script :file:`conf.py` used to -set various document parameters. The makefile can be used for a variety of -targets; invoke `make help` in any of these directories for a listing of -available output formats. For convenience, there is a top-level -:file:`Makefile.am` that has targets for PDF and HTML documentation for both -developer and user documentation, respectively. That makefile is also -responsible for building manual pages packed with distribution builds. ++-----------------------+-------------------------------------------+ +| Directory | Contents | ++=======================+===========================================+ +| :file:`doc/user` | User documentation; configuration guides; | +| | protocol overviews | ++-----------------------+-------------------------------------------+ +| :file:`doc/developer` | Developer's documentation; API specs; | +| | datastructures; architecture overviews; | +| | project management procedure | ++-----------------------+-------------------------------------------+ +| :file:`doc/manpages` | Source for manpages | ++-----------------------+-------------------------------------------+ +| :file:`doc/figures` | Images and diagrams | ++-----------------------+-------------------------------------------+ +| :file:`doc/extra` | Miscellaneous Sphinx extensions, scripts, | +| | customizations, etc. | ++-----------------------+-------------------------------------------+ + +Each of these directories, with the exception of :file:`doc/figures` and +:file:`doc/extra`, contains a Sphinx-generated Makefile and configuration +script :file:`conf.py` used to set various document parameters. The makefile +can be used for a variety of targets; invoke `make help` in any of these +directories for a listing of available output formats. For convenience, there +is a top-level :file:`Makefile.am` that has targets for PDF and HTML +documentation for both developer and user documentation, respectively. That +makefile is also responsible for building manual pages packed with distribution +builds. Indent and styling should follow existing conventions: @@ -890,6 +896,15 @@ your implementation of a new BGP draft should go in the BGP chapter instead of being its own chapter. If you are adding a new protocol daemon, please create a new chapter. +FRR Specific Markup +------------------- + +FRR has some customizations applied to the Sphinx markup that go a long way +towards making documentation easier to use, write and maintain. + +CLI Commands +^^^^^^^^^^^^ + When documenting CLI please use a combination of the ``.. index::`` and ``.. clicmd::`` directives. For example, the command :clicmd:`show pony` would be documented as follows: @@ -923,6 +938,29 @@ When documented this way, CLI commands can be cross referenced with the This is very helpful for users who want to quickly remind themselves what a particular command does. +Configuration Snippets +^^^^^^^^^^^^^^^^^^^^^^ + +When putting blocks of example configuration please use the +``.. code-block::`` directive and specify ``frr`` as the highlighting language, +as in the following example. This will tell Sphinx to use a custom Pygments +lexer to highlight FRR configuration syntax. + +.. code-block:: rest + + .. code-block:: frr + + ! + ! Example configuration file. + ! + log file /tmp/log.log + service integrated-vtysh-config + ! + ip route 1.2.3.0/24 reject + ipv6 route de:ea:db:ee:ff::/64 reject + ! + + .. _GitHub: https://github.com/frrouting/frr .. _GitHub issues: https://github.com/frrouting/frr/issues |