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``.
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``.
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``.
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:
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:
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
--- /dev/null
+# -*- coding: utf-8 -*-
+# Copyright (c) 2017 Vincent Bernat <bernat@luffy.cx>
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+from pygments.lexer import RegexLexer, bygroups
+from pygments.token import Text, Comment, Keyword
+from pygments.token import String, Number, Name
+
+
+class FRRLexer(RegexLexer):
+ name = "frr"
+ aliases = ["frr"]
+ tokens = {
+ 'root': [
+ (r'^[ \t]*!.*?\n', Comment.Singleline),
+ (r'"(\\\\|\\"|[^"])*"', String.Double),
+ (r'[a-f0-9]*:[a-f0-9]*:[a-f0-9:]*(:\d+\.\d+\.\d+\.\d+)?(/\d+)?',
+ Number), # IPv6
+ (r'\d+\.\d+\.\d+\.\d+(/\d+)?', Number), # IPv4
+ (r'^([ \t]*)(no[ \t]+)?([-\w]+)',
+ bygroups(Text, Keyword, Name.Function)),
+ (r'[ \t]+', Text),
+ (r'\n', Text),
+ (r'\d+', Number),
+ (r'\S+', Text),
+ ],
+ }