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/VERSION b/VERSION
index a158d08..b630701 100755
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.10.6
+2.10.7
diff --git a/conf.py b/conf.py
index 6d4ef01..8cb9c93 100644
--- a/conf.py
+++ b/conf.py
@@ -11,10 +11,6 @@
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
import os
@@ -25,12 +21,11 @@
# -- Project information -----------------------------------------------------
project = u'VOLTHA Docs'
-copyright = u'2019-2021, VOLTHA Contributors & Open Networking Foundation'
+copyright = u'2019-2022, VOLTHA Contributors & Open Networking Foundation'
author = u'VOLTHA Contributors'
# The short X.Y version
version = get_version()
-
# The full version, including alpha/beta/rc tags
release = version
@@ -49,6 +44,7 @@
extensions = [
'recommonmark',
'sphinx.ext.coverage',
+ 'sphinx.ext.extlinks',
'sphinx.ext.graphviz',
'sphinx.ext.ifconfig',
'sphinx.ext.mathjax',
@@ -74,7 +70,7 @@
# Text files with lists of words that shouldn't fail the spellchecker:
spelling_word_list_filename=['dict.txt', ]
-# sphinx-multiversion prep, run in each versioned source directory
+#sphinx-multiversion prep, run in each versioned source directory
prep_commands = [
'ln -sf _root_/repos _target_/repos',
'make prep',
@@ -267,6 +263,16 @@
"_static/fonts/Inconsolata-Bold.ttf",
]
+# -- Options for extlinks extension ------------------------------------------
+# ..seealso: https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
+# 'vhc' : 'https://gerrit.opencord.org/plugins/gitiles/voltha-helm-charts',
+extlinks=\
+ {
+ 'vol-jira' : ('https://jira.opencord.org/projects/VOL/issues/%s', 'jira::%s'),
+ 'vol-ger' : ('https://gerrit.opencord.org/plugins/gitiles/%s', 'gerrit::%s'),
+ 'vol-git' : ('https://github.com/opencord/%s', 'git::%s'),
+ }
+
# -- Options for todo extension ----------------------------------------------
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
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.
