docs.voltha.org::HOWTO edits and WARNING cleanups.
Makefile
--------
o Added convenience target 'make warnings' to help search for problems.
config.py
---------
o Add more exclusions for .venv/ so sphinx will stop checking sources.
howto/edit_voltha_docs.rts
howto/docs.voltha.org/index.rst
howto/docs.voltha.org/quickstart.rst
howto/docs.voltha.org/edit_voltha_docs.rst
------------------------------------------
o Added a quickstart guide for editing repo:voltha-docs
Misc
----
o Fixed several WARNINGS
o Add missing documents in index.rst
Change-Id: I0b3d01cc4116d40bd84db49649669253d6135546
diff --git a/howto/docs.voltha.org/edit_voltha_docs.rst b/howto/docs.voltha.org/edit_voltha_docs.rst
new file mode 100644
index 0000000..a5d8009
--- /dev/null
+++ b/howto/docs.voltha.org/edit_voltha_docs.rst
@@ -0,0 +1,114 @@
+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`
+
+Documentation Guide
+===================
+
+Building the Docs
+"""""""""""""""""
+
+Building requires python, creates a virtualenv (``.venv``) which has all the
+necessary tools.
+
+Run ``make html`` to generate html documentation in ``_build/html``.
+
+Run ``make reload`` to get a live reload in your browser (refreshes on document
+save).
+
+Run ``make latexpdf`` to generate html documentation in ``_build/latex``.
+Requires that you have a recent LaTeX installation and ``latexmk`` installed
+
+Writing Docs
+""""""""""""
+
+Docs written using sphinx: https://www.sphinx-doc.org/en/master/
+
+Documentation is done in reStructuredText or Markdown, but only ``.rst`` files
+can contain embedded diagrams.
+
+Guides for RST:
+
+- https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
+- https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
+
+RST has multiple heading formats possible, the ones we're using are in the
+order for the HTML h1-h5: ``=``, ``-`` ``"``, ``'``, ``^``.
+
+
+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>`
+- howto/docs.voltha/org/quickstart
diff --git a/howto/docs.voltha.org/index.rst b/howto/docs.voltha.org/index.rst
new file mode 100644
index 0000000..fffaf7d
--- /dev/null
+++ b/howto/docs.voltha.org/index.rst
@@ -0,0 +1,8 @@
+HOWTO: docs.voltha.org
+======================
+
+.. toctree::
+ :maxdepth: 1
+
+ quickstart
+ edit_voltha_docs
diff --git a/howto/docs.voltha.org/quickstart.rst b/howto/docs.voltha.org/quickstart.rst
new file mode 100644
index 0000000..25743fe
--- /dev/null
+++ b/howto/docs.voltha.org/quickstart.rst
@@ -0,0 +1,116 @@
+Quickstart Guide: Editing
+=========================
+
+Intent
+------
+
+This quickstart guide decribes how to modify and commit changes that will
+be visible on http://docs.voltha.org.
+
+Clone repo:voltha-docs
+----------------------
+
+.. code:: bash
+
+ # Clone repo:voltha-docs
+ git clone ssh://gerrit.opencord.org:29418/voltha-docs.git
+
+ # Create a developer branch
+ git checkout -b dev-joey
+
+.. code-block: shell-session
+ :linenos: 2
+
+ # Clone repo:voltha-docs
+ git clone ssh://gerrit.opencord.org:29418/voltha-docs.git
+
+ # Create a developer branch
+ git checkout -b dev-joey
+
+Repositories:
+`gerrit <https://gerrit.opencord.org/plugins/gitiles/voltha-docs>`_
+`github <https://github.com/opencord/voltha-docs>`_
+
+.. code-block: shell-session
+ :linenos: 2,5
+
+ # Clone repo:voltha-docs
+ git clone ssh://gerrit.opencord.org:29418/voltha-docs.git
+
+ # Create a developer branch
+ git checkout -b dev-joey
+
+Interactive development
+-----------------------
+
+.. code-block: shell-session
+ :caption: Launch a browser for viewing local edits
+ :linenos: 4
+
+ cd voltha-docs
+ make reload
+
+- source edit: modify reStructuredText (RST) sources
+- Modify content to taste
+
+Invoke checkin tests locally
+----------------------------
+
+.. code-block: shell-session
+ :linenos: 3
+
+ cd voltha-docs
+ make sterile
+ make test
+
+.. list-table:: makefile targets for testing
+ :widths: 30,50
+ :header-rows: 2
+
+ * - make target
+ - Description
+ * -
+ -
+ * - make test
+ - Kitchen sink target: invokes all checkin tests (make lint linkcheck)
+ * - make lint
+ - Syntax check by source: rst, python
+ * - make linkcheck
+ - Verify URLs inlined within rst files are valid
+
+Document and commit changes for ``git log``
+-------------------------------------------
+
+.. code-block: shell-session
+ :linenos:
+
+ # Commit message: Line 1 symmarize changes with jira ticket linkage.
+ echo '[VOL-XXXX] update voltha.docs' > commit_message
+
+ # Commit message: Capture list of modified files
+ git status >> commit_message
+
+ # Commit message: Capture source diffs
+ git diff >> commit_message
+
+ # Summarize changes for git log
+ $EDIT commit_message
+
+ # git add <modified files>
+
+ # Commit changes to revision control
+ git commit -F commit_message
+
+ # Rebase your sandbox, merge branch=master into branch=dev-joey
+ ... git rebase documentation URL needed here ...
+
+ # Create a patch and request a code review
+ git review --reviewers email1 email2 email3
+
+Extra credit
+-------------------------------------------
+
+.. code-block: shell-session
+
+ make sterile
+ make html 2>&1 | sed -e 's/WARNING/\nWARNING/g' | less --ignore-case --hilite-search '/WARNING'