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>`
diff --git a/howto/images/gerrit_dashboard.png b/howto/images/gerrit_dashboard.png
new file mode 100644
index 0000000..f3e8e38
--- /dev/null
+++ b/howto/images/gerrit_dashboard.png
Binary files differ
diff --git a/howto/images/menu_repositories.png b/howto/images/menu_repositories.png
new file mode 100644
index 0000000..25b1141
--- /dev/null
+++ b/howto/images/menu_repositories.png
Binary files differ
diff --git a/howto/images/repository_select_VOLTHA.png b/howto/images/repository_select_VOLTHA.png
new file mode 100644
index 0000000..205924b
--- /dev/null
+++ b/howto/images/repository_select_VOLTHA.png
Binary files differ
diff --git a/howto/voltha_repositories.rst b/howto/voltha_repositories.rst
new file mode 100644
index 0000000..73897e8
--- /dev/null
+++ b/howto/voltha_repositories.rst
@@ -0,0 +1,56 @@
+.. _voltha_repositories:
+
+VOLTHA project repositories
+===========================
+
+Finding a repository to work with
+---------------------------------
+
+Navigate to the VOLTHA repositories on gerrit or github:
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+- :vol-ger:`voltha-docs`
+- :vol-git:`voltha-docs`
+
+- https://github.com/opencord/voltha-docs
+
+|
+
+Visit gerrit.opencord.org/dashboard
+"""""""""""""""""""""""""""""""""""
+
+.. figure:: images/gerrit_dashboard.png
+ :alt: Gerrit dashboard
+ :width: 70%
+ :align: center
+
+|
+
+From the BROWSE pull-down menu select Repositories
+""""""""""""""""""""""""""""""""""""""""""""""""""
+.. figure:: images/menu_repositories.png
+ :alt: BROWSE pull-down menu selection
+ :align: center
+
+|
+
+In the Filter: box search for 'voltha-'
+"""""""""""""""""""""""""""""""""""""""
+
+- Click browse to view repository clone command and available versions.
+- Click branch=master to browse the code base.
+
+.. figure:: images/repository_select_VOLTHA.png
+ :alt: voltha- repository search
+ :width: 70%
+ :align: center
+
+|
+
+
+Github
+++++++
+A mirror of the VOLTHA gerrit repositories can also be found on github.
+
+- https://github.com/opencord/voltha-docs
+
+ - Gerrit repositories can also be accessed through a mirror on github.
