| Joey Armstrong | 2cab6b4 | 2022-09-08 12:59:42 -0400 | [diff] [blame] | 1 | Modify docs.voltha.org |
| 2 | ====================== |
| 3 | |
| Joey Armstrong | bbd71d6 | 2022-10-12 11:51:35 -0400 | [diff] [blame] | 4 | Docs for VOLTHA can be found on the website or via web search |
| 5 | """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
| Joey Armstrong | 2cab6b4 | 2022-09-08 12:59:42 -0400 | [diff] [blame] | 6 | - https://docs.voltha.org |
| 7 | - https://docs.voltha.org/master/index.html |
| 8 | |
| 9 | - Note: Google search may return an older doc version for topics. |
| 10 | - Navigate to /master/index.html and use the builtin searchbox to always view current documentation for VOLTHA. |
| 11 | |
| Joey Armstrong | bbd71d6 | 2022-10-12 11:51:35 -0400 | [diff] [blame] | 12 | Browse repository content |
| 13 | """"""""""""""""""""""""" |
| 14 | - :vol-ger:`voltha-docs` |
| 15 | - :vol-git:`voltha-docs` |
| Joey Armstrong | 2cab6b4 | 2022-09-08 12:59:42 -0400 | [diff] [blame] | 16 | |
| Joey Armstrong | 2cab6b4 | 2022-09-08 12:59:42 -0400 | [diff] [blame] | 17 | |
| Joey Armstrong | bbd71d6 | 2022-10-12 11:51:35 -0400 | [diff] [blame] | 18 | Checkout, modify and test |
| 19 | """"""""""""""""""""""""" |
| Joey Armstrong | 2cab6b4 | 2022-09-08 12:59:42 -0400 | [diff] [blame] | 20 | |
| 21 | .. sourcecode:: shell |
| 22 | |
| 23 | $ git clone ssh://gerrit.opencord.org:29418/voltha-docs |
| 24 | |
| 25 | $ cd voltha-docs |
| 26 | $ vi *.rst |
| 27 | $ make html # doc generation |
| Joey Armstrong | bbd71d6 | 2022-10-12 11:51:35 -0400 | [diff] [blame] | 28 | $ make lint # syntax checking |
| Joey Armstrong | 2cab6b4 | 2022-09-08 12:59:42 -0400 | [diff] [blame] | 29 | $ make test # syntax check *.rst files |
| Joey Armstrong | 36592e3 | 2022-11-28 09:00:28 -0500 | [diff] [blame] | 30 | $ make docs # generate website pages |
| Joey Armstrong | 2cab6b4 | 2022-09-08 12:59:42 -0400 | [diff] [blame] | 31 | |
| 32 | $ "$BROWSER" _build/html/index.html # BROWSER='firefox' |
| Joey Armstrong | bbd71d6 | 2022-10-12 11:51:35 -0400 | [diff] [blame] | 33 | |
| 34 | |
| Joey Armstrong | 7340999 | 2022-12-14 20:21:56 -0500 | [diff] [blame^] | 35 | Interactive editing: real time updates |
| 36 | """""""""""""""""""""""""""""""""""""" |
| 37 | |
| 38 | Another useful convenience makefile target to try is the reload target. |
| 39 | "make reload" will invoke the sphinx-reload program, spawn a web page for |
| 40 | viewing html documentation pages followed by periodic regeneration of page |
| 41 | content. |
| 42 | |
| 43 | .. sourcecode:: shell |
| 44 | |
| 45 | $ git clone ssh://gerrit.opencord.org:29418/voltha-docs |
| 46 | |
| 47 | $ cd voltha-docs |
| 48 | $ make reload |
| 49 | $ vi *.rst |
| 50 | |
| 51 | |
| Joey Armstrong | bbd71d6 | 2022-10-12 11:51:35 -0400 | [diff] [blame] | 52 | make lint (syntax checking) |
| 53 | """"""""""""""""""""""""""" |
| 54 | - `make help (pending) <https://gerrit.opencord.org/c/voltha-system-tests/+/33306>` |
| 55 | |
| 56 | .. sourcecode:: shell |
| 57 | |
| 58 | $ make help |
| 59 | $ USAGE: make target [, target(s)] |
| 60 | $ |
| 61 | $ [LINT] |
| 62 | $ lint-json Syntax check json sources |
| 63 | $ lint-python Syntax check using pylint and flake8 |
| 64 | $ lint-robot Syntax check robot sources using rflint |
| 65 | $ lint-yaml Syntax check yaml source using yamllint |
| 66 | $ |
| 67 | $ make lint |
| 68 | |
| 69 | |
| 70 | make html |
| 71 | """"""""" |
| 72 | - Install python packages: sphinx, pylint, flake8 |
| 73 | - Invoke sphinx to generate documentation. |
| 74 | |
| 75 | |
| 76 | See Also |
| 77 | """""""" |
| 78 | - `RST Markup Documentation <https://rstdoc.readthedocs.io/en/latest>` |
| 79 | - `Sphinx Documentation <https://www.sphinx-doc.org/en/master>` |
| 80 | - `RST Markup Specification <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>` |