Documentation #1704
Documentation #1704
Conversation
* Move doc/code/ -> doc/developer/ * Move disparate code documentation to doc/developer/ * Convert Markdown docs to reStructuredText * Organize docs into Sphinx tree * Move build docs -> doc/developer/ * Change build doc titles to fit under Building subsection of manual Signed-off-by: Quentin Young <[email protected]>
Update, embellish, clarify. Signed-off-by: Quentin Young <[email protected]>
Signed-off-by: Quentin Young <[email protected]>
* Add chapter on BGPD * Add diagram for git workflow * Convert next-hop tracking documents to ReST * Update & organize workflow document * Move ldpd docs back up to the parent directory Signed-off-by: Quentin Young <[email protected]>
Signed-off-by: Quentin Young <[email protected]>
Signed-off-by: Quentin Young <[email protected]>
Lou wrote his own clause so we're using that one This reverts commit 558669e.
Missed hidden files when shuffling things around. Restore David's makefiles & gitignore. Signed-off-by: Quentin Young <[email protected]>
Automatically translated all Texinfo files to RST using a script found on the GCC mailing list[0]. Some formatting manually corrected. Also created index.rst for building as well as boilerplate Sphinx conf.py and Makefile. [0] https://gcc.gnu.org/ml/gcc-patches/2015-11/msg01095.html Signed-off-by: Quentin Young <[email protected]>
Manual cleanup from leftover texi -> rst Signed-off-by: Quentin Young <[email protected]>
Signed-off-by: Quentin Young <[email protected]>
Signed-off-by: Quentin Young <[email protected]>
The old Texi docs had some Makefile-style variable substitutions they used to pull in information like release date, configured install path, etc. Sphinx has this ability as well, we start making use of it here. Signed-off-by: Quentin Young <[email protected]>
Will probably need more cleanup. Signed-off-by: Quentin Young <[email protected]>
In conf.py, extract & construct values for inline variables throughout the docs. In the docs, use these inline variables in RST syntax. Signed-off-by: Quentin Young <[email protected]>
Signed-off-by: Quentin Young <[email protected]>
Just reading through the docs and fixing bugs as I go. Signed-off-by: Quentin Young <[email protected]>
This is an incomplete stub of a chapter and goes under BGP docs anyway. Also fix an include statement for RPKI. Signed-off-by: Quentin Young <[email protected]>
accidentally removed in older commit Signed-off-by: Quentin Young <[email protected]>
This name hasn't made sense for a long time. Signed-off-by: Quentin Young <[email protected]>
Don't need these in RST Signed-off-by: Quentin Young <[email protected]>
Signed-off-by: Quentin Young <[email protected]>
Use program and option directives for CLI options Signed-off-by: Quentin Young <[email protected]>
Signed-off-by: Quentin Young <[email protected]>
Signed-off-by: Quentin Young <[email protected]>
Signed-off-by: Quentin Young <[email protected]>
* Use new 'clicmd' directive / role * Convert old style range syntax to new style Signed-off-by: Quentin Young <[email protected]>
Signed-off-by: Quentin Young <[email protected]>
Signed-off-by: Quentin Young <[email protected]>
Signed-off-by: Quentin Young <[email protected]>
Continuous Integration Result: SUCCESSFULCongratulations, this patch passed basic tests Tested-by: NetDEF / OpenSourceRouting.org CI System CI System Testrun URL: https://ci1.netdef.org/browse/FRR-FRRPULLREQ-2800/ This is a comment from an EXPERIMENTAL automated CI system. CLANG Static Analyzer Summary
No Changes in Static Analysis warnings compared to base19 Static Analyzer issues remaining.See details at |
|
@louberger I have addressed 1 and 2. Please verify. I don't think 3 should block the PR, we can update the doc contents later after the proper solution has been determined. |
|
@qlyoung |
|
@qlyoung ' Build finished. The manual pages are in _build/man. |
|
@qlyoung WRT 3: I'll talk to martin and come back with a proposed fix. One of us can add it to the PR |
|
New issue (#4): parallel makes sometimes fail. I reproduced using and 8 core machine and 'make -j 8' on a clean build, Note it doesn't always fail! this is output after a make clean: make[3]: Entering directory `.../doc/user' Build finished. The HTML pages are in _build/html. |
Sphinx is not designed to be run in parallel and exhibits filesystem race conditions if it is. Disable parallel build. Signed-off-by: Quentin Young <[email protected]>
Since docs are rebuilt on every make invocation, don't bother building html by default to save a bit of time. Signed-off-by: Quentin Young <[email protected]>
|
@louberger Regarding 2, I noticed that, the Sphinx generated makefile always rebuilds them. It is slightly inefficient (couple extra seconds on the build time) but it keeps the makefile tree much cleaner, easier to understand and closer to the canonical Sphinx system. Right now I have For the parallel issue it looks like this is not a supported mode of Sphinx; while it supports building each target in parallel itself, building multiple targets in parallel causes filesystem race conditions as per sphinx-doc/sphinx#2946. I therefore disabled parallel make in the |
💚 Basic BGPD CI results: SUCCESS, 0 tests failedResults table
For details, please contact louberger |
Continuous Integration Result: SUCCESSFULCongratulations, this patch passed basic tests Tested-by: NetDEF / OpenSourceRouting.org CI System CI System Testrun URL: https://ci1.netdef.org/browse/FRR-FRRPULLREQ-2823/ This is a comment from an EXPERIMENTAL automated CI system. CLANG Static Analyzer Summary
No Changes in Static Analysis warnings compared to base19 Static Analyzer issues remaining.See details at |
Signed-off-by: Quentin Young <[email protected]>
Signed-off-by: Quentin Young <[email protected]>
💚 Basic BGPD CI results: SUCCESS, 0 tests failedResults table
For details, please contact louberger |
Continuous Integration Result: SUCCESSFULCongratulations, this patch passed basic tests Tested-by: NetDEF / OpenSourceRouting.org CI System CI System Testrun URL: https://ci1.netdef.org/browse/FRR-FRRPULLREQ-2869/ This is a comment from an EXPERIMENTAL automated CI system. CLANG Static Analyzer Summary
No Changes in Static Analysis warnings compared to base19 Static Analyzer issues remaining.See details at |
Signed-off-by: Martin Winter <[email protected]>
Signed-off-by: Quentin Young <[email protected]>
Continuous Integration Result: SUCCESSFULCongratulations, this patch passed basic tests Tested-by: NetDEF / OpenSourceRouting.org CI System CI System Testrun URL: https://ci1.netdef.org/browse/FRR-FRRPULLREQ-2872/ This is a comment from an EXPERIMENTAL automated CI system. CLANG Static Analyzer Summary
No Changes in Static Analysis warnings compared to base19 Static Analyzer issues remaining.See details at |
Makefile.amI have built PDF and HTML version of the docs which you can preview here:
http://45.33.5.119/
Docs on how to build the docs can be found in the docs:
http://45.33.5.119/dev-guide/workflow.html#documentation
I am sure there are some minor mistakes left over since I ended up manually translating Texinfo to RST. It builds cleanly in Sphinx, any nits I will solve incrementally in later PRs.