blob: 17beb08f2a5249e2f30bfb5b9d5ac93d025ec335 [file] [log] [blame]
Modify docs.voltha.org
======================
Docs for VOLTHA can be found on the website or via web search
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
- https://docs.voltha.org
- https://docs.voltha.org/master/index.html
- Note: Google search may return an older doc version for topics.
- Navigate to /master/index.html and use the builtin searchbox to always view current documentation for VOLTHA.
Browse repository content
"""""""""""""""""""""""""
- :vol-ger:`voltha-docs`
- :vol-git:`voltha-docs`
Checkout, modify and test
"""""""""""""""""""""""""
.. sourcecode:: shell
$ git clone ssh://gerrit.opencord.org:29418/voltha-docs
$ cd voltha-docs
$ vi *.rst
$ make html # doc generation
$ make lint # syntax checking
$ make test # syntax check *.rst files
$ make docs # generate website pages
$ "$BROWSER" _build/html/index.html # BROWSER='firefox'
Interactive editing: real time updates
""""""""""""""""""""""""""""""""""""""
Another useful convenience makefile target to try is the reload target.
"make reload" will invoke the sphinx-reload program, spawn a web page for
viewing html documentation pages followed by periodic regeneration of page
content.
.. sourcecode:: shell
$ git clone ssh://gerrit.opencord.org:29418/voltha-docs
$ cd voltha-docs
$ make reload
$ vi *.rst
make lint (syntax checking)
"""""""""""""""""""""""""""
- `make help (pending) <https://gerrit.opencord.org/c/voltha-system-tests/+/33306>`
.. sourcecode:: shell
$ make help
$ USAGE: make target [, target(s)]
$
$ [LINT]
$ lint-json Syntax check json sources
$ lint-python Syntax check using pylint and flake8
$ lint-robot Syntax check robot sources using rflint
$ lint-yaml Syntax check yaml source using yamllint
$
$ make lint
make html
"""""""""
- Install python packages: sphinx, pylint, flake8
- Invoke sphinx to generate documentation.
See Also
""""""""
- `RST Markup Documentation <https://rstdoc.readthedocs.io/en/latest>`
- `Sphinx Documentation <https://www.sphinx-doc.org/en/master>`
- `RST Markup Specification <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>`