conf.py
----
* Import extension sphinx.ext.extlinks for rewriting/shortening URLs.
* Define extlinks vol-{git,ger,jira} for documenting.
howto/edit_voltha_docs.rst
----
* Build out docs for make lint and make html.
* Include iamge files from an earlier howto patch to help get content in.
howto/voltha_repositories.rst
----
* Pull in docs from another howto patch.
* Describe gerrit and git repos.
Bump the copyright revision string to 2022.
Change-Id: Iacc139d764682d586c2cd88150c8e1795e479662
diff --git a/howto/edit_voltha_docs.rst b/howto/edit_voltha_docs.rst
index 463e86c..b63c44f 100644
--- a/howto/edit_voltha_docs.rst
+++ b/howto/edit_voltha_docs.rst
@@ -1,19 +1,22 @@
Modify docs.voltha.org
======================
-Docs for VOLTHA can be found on the website or via web search:
-
+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:
+Browse repository content
+"""""""""""""""""""""""""
+- :vol-ger:`voltha-docs`
+- :vol-git:`voltha-docs`
-- https://gerrit.opencord.org/plugins/gitiles/voltha-docs
-Checkout, modify and test:
+Checkout, modify and test
+"""""""""""""""""""""""""
.. sourcecode:: shell
@@ -22,6 +25,38 @@
$ cd voltha-docs
$ vi *.rst
$ make html # doc generation
+ $ make lint # syntax checking
$ make test # syntax check *.rst files
$ "$BROWSER" _build/html/index.html # BROWSER='firefox'
+
+
+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>`