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 <qlyoung@cumulusnetworks.com>
Update, embellish, clarify. Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
* 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 <qlyoung@cumulusnetworks.com>
Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
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 <qlyoung@cumulusnetworks.com>
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 <qlyoung@cumulusnetworks.com>
Manual cleanup from leftover texi -> rst Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
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 <qlyoung@cumulusnetworks.com>
Will probably need more cleanup. Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
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 <qlyoung@cumulusnetworks.com>
Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
Just reading through the docs and fixing bugs as I go. Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
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 <qlyoung@cumulusnetworks.com>
accidentally removed in older commit Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
This name hasn't made sense for a long time. Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
Use program and option directives for CLI options Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
* Use new 'clicmd' directive / role * Convert old style range syntax to new style Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
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 <qlyoung@cumulusnetworks.com>
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 <qlyoung@cumulusnetworks.com>
|
@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 <qlyoung@cumulusnetworks.com>
Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
💚 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 <mwinter@opensourcerouting.org>
Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
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.