blob: 540b734cb3101148c6d058af213279fbaa8d4e9a [file] [log] [blame]
Joey Armstrong2cab6b42022-09-08 12:59:42 -04001Modify docs.voltha.org
2======================
3
Joey Armstrongbbd71d62022-10-12 11:51:35 -04004Docs for VOLTHA can be found on the website or via web search
5"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Joey Armstrong2cab6b42022-09-08 12:59:42 -04006- 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 Armstrongbbd71d62022-10-12 11:51:35 -040012Browse repository content
13"""""""""""""""""""""""""
14- :vol-ger:`voltha-docs`
15- :vol-git:`voltha-docs`
Joey Armstrong2cab6b42022-09-08 12:59:42 -040016
Joey Armstrong1a9b7d12022-12-19 14:13:07 -050017Documentation Guide
18===================
19
20Building the Docs
21"""""""""""""""""
22
23Building requires python, creates a virtualenv (``doc_venv``) which has all the
24necessary tools.
25
26Run ``make html`` to generate html documentation in ``_build/html``.
27
28Run ``make reload`` to get a live reload in your browser (refreshes on document
29save).
30
31Run ``make latexpdf`` to generate html documentation in ``_build/latex``.
32Requires that you have a recent LaTeX installation and ``latexmk`` installed
33
34Writing Docs
35""""""""""""
36
37Docs written using sphinx: http://www.sphinx-doc.org
38
39Documentation is done in reStructuredText or Markdown, but only ``.rst`` files
40can contain embedded diagrams.
41
42Guides for RST:
43
44- https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
Joey Armstrong8388b7f2023-01-23 11:20:04 -050045- https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
Joey Armstrong1a9b7d12022-12-19 14:13:07 -050046
47RST has multiple heading formats possible, the ones we're using are in the
48order for the HTML h1-h5: ``=``, ``-`` ``"``, ``'``, ``^``.
49
Joey Armstrong2cab6b42022-09-08 12:59:42 -040050
Joey Armstrongbbd71d62022-10-12 11:51:35 -040051Checkout, modify and test
52"""""""""""""""""""""""""
Joey Armstrong2cab6b42022-09-08 12:59:42 -040053
54.. sourcecode:: shell
55
56 $ git clone ssh://gerrit.opencord.org:29418/voltha-docs
57
58 $ cd voltha-docs
59 $ vi *.rst
60 $ make html # doc generation
Joey Armstrongbbd71d62022-10-12 11:51:35 -040061 $ make lint # syntax checking
Joey Armstrong2cab6b42022-09-08 12:59:42 -040062 $ make test # syntax check *.rst files
Joey Armstrong36592e32022-11-28 09:00:28 -050063 $ make docs # generate website pages
Joey Armstrong2cab6b42022-09-08 12:59:42 -040064
65 $ "$BROWSER" _build/html/index.html # BROWSER='firefox'
Joey Armstrongbbd71d62022-10-12 11:51:35 -040066
67
Joey Armstrong73409992022-12-14 20:21:56 -050068Interactive editing: real time updates
69""""""""""""""""""""""""""""""""""""""
70
71Another useful convenience makefile target to try is the reload target.
72"make reload" will invoke the sphinx-reload program, spawn a web page for
73viewing html documentation pages followed by periodic regeneration of page
74content.
75
76.. sourcecode:: shell
77
78 $ git clone ssh://gerrit.opencord.org:29418/voltha-docs
79
80 $ cd voltha-docs
81 $ make reload
82 $ vi *.rst
83
84
Joey Armstrongbbd71d62022-10-12 11:51:35 -040085make lint (syntax checking)
86"""""""""""""""""""""""""""
87- `make help (pending) <https://gerrit.opencord.org/c/voltha-system-tests/+/33306>`
88
89.. sourcecode:: shell
90
91 $ make help
92 $ USAGE: make target [, target(s)]
93 $
94 $ [LINT]
95 $ lint-json Syntax check json sources
96 $ lint-python Syntax check using pylint and flake8
97 $ lint-robot Syntax check robot sources using rflint
98 $ lint-yaml Syntax check yaml source using yamllint
99 $
100 $ make lint
101
102
103make html
104"""""""""
105- Install python packages: sphinx, pylint, flake8
106- Invoke sphinx to generate documentation.
107
108
109See Also
110""""""""
111- `RST Markup Documentation <https://rstdoc.readthedocs.io/en/latest>`
112- `Sphinx Documentation <https://www.sphinx-doc.org/en/master>`
113- `RST Markup Specification <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>`