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/Makefile b/Makefile
index 7d76ccb..3de80c0 100644
--- a/Makefile
+++ b/Makefile
@@ -191,6 +191,22 @@
&& $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
## -----------------------------------------------------------------------
+## Intent: Display WARNINGS buried in sphinx output
+## -----------------------------------------------------------------------
+warnings-log := warnings.log
+warnings:
+ $(MAKE) html 2>&1 \
+ | sed -e 's@\([Ww][Aa][Rr][Nn][Ii][Nn][Gg]\)@\n\1@g' \
+ > "$(warnings-log)"
+ less --ignore-case --hilite-search --pattern='/warning' $(warnings-log)
+
+clean::
+ $(RM) $(warnings-log)
+
+help ::
+ @echo " warnings Display WARNING strings buried in sphinx output"
+
+## -----------------------------------------------------------------------
## Intent: Display make hel footer
## -----------------------------------------------------------------------
include $(MAKEDIR)/help/trailer.mk
diff --git a/VERSION b/VERSION
index 6e44ecb..56beced 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.12.4-dev
+2.12.4
diff --git a/conf.py b/conf.py
index cfd7dd4..9290b6f 100644
--- a/conf.py
+++ b/conf.py
@@ -88,7 +88,9 @@
]
# don't include tags
-smv_tag_whitelist = None
+# smv_tag_whitelist = None
+# smv_tag_whitelist = disabled^ # Was = None
+smv_tag_whitelist = 'disabled_a^' # Was = None
# inlcude only the branches matching master and voltha-*
smv_branch_whitelist = r'^(master|voltha-.*)$'
@@ -138,9 +140,12 @@
'CODE_OF_CONDUCT.md',
'*/CODE_OF_CONDUCT.md',
# Ignore all:
+ '__pycache__',
'**/__pycache__', # generated - faster traversal
+ '.venv',
+ '**/.venv', # external virtual env
# Revisit: one directory pattern is sufficient.
- '**/doc_venv',
+ '**/doc_venv',
'**/venv_docs',
'**/virtualenv',
'**/vst_venv',
diff --git a/howto/edit_voltha_docs.rst b/howto/docs.voltha.org/edit_voltha_docs.rst
similarity index 96%
rename from howto/edit_voltha_docs.rst
rename to howto/docs.voltha.org/edit_voltha_docs.rst
index 32bcf9d..a5d8009 100644
--- a/howto/edit_voltha_docs.rst
+++ b/howto/docs.voltha.org/edit_voltha_docs.rst
@@ -20,7 +20,7 @@
Building the Docs
"""""""""""""""""
-Building requires python, creates a virtualenv (``doc_venv``) which has all the
+Building requires python, creates a virtualenv (``.venv``) which has all the
necessary tools.
Run ``make html`` to generate html documentation in ``_build/html``.
@@ -111,3 +111,4 @@
- `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'
diff --git a/howto/index.rst b/howto/index.rst
index 2df281b..276a721 100644
--- a/howto/index.rst
+++ b/howto/index.rst
@@ -5,7 +5,11 @@
:maxdepth: 2
code/index
- edit_voltha_docs
+ docs.voltha.org/index
release/index
ssh_access
voltha_repositories
+
+ accounts
+ development
+ eof
diff --git a/howto/release/components/index.rst b/howto/release/components/index.rst
index 02bd2a9..77c45c5 100644
--- a/howto/release/components/index.rst
+++ b/howto/release/components/index.rst
@@ -8,7 +8,8 @@
onos_dependencies
voltha-protos
- voltctl/index
- voltctl/install
- voltctl/release
- voltctl/see_also
+ voltha-go.rst
+ voltha-lib-go
+ voltha-onos
+ voltha-openolt-adapter
+ voltha-openonu-adapter-go
diff --git a/howto/release/index.rst b/howto/release/index.rst
index 6dfa10f..ce276ee 100644
--- a/howto/release/index.rst
+++ b/howto/release/index.rst
@@ -14,6 +14,8 @@
voltha-docs/index
post-release/index
+ charts/index
+
voltctl/index
voltctl/install
voltctl/release
diff --git a/howto/release/post-release/index.rst b/howto/release/post-release/index.rst
index 3aadb95..019babb 100644
--- a/howto/release/post-release/index.rst
+++ b/howto/release/post-release/index.rst
@@ -2,7 +2,7 @@
=========================
.. toctree::
- :maxddepth 1
+ :maxdepth: 1
gitreview
diff --git a/howto/release/voltha-docs/index.rst b/howto/release/voltha-docs/index.rst
index 0878da1..2d3441b 100644
--- a/howto/release/voltha-docs/index.rst
+++ b/howto/release/voltha-docs/index.rst
@@ -10,3 +10,4 @@
:maxdepth: 1
release_notes
+ create_lts_view
diff --git a/overview/release_process.rst b/overview/release_process.rst
index bee4a49..b76c6db 100644
--- a/overview/release_process.rst
+++ b/overview/release_process.rst
@@ -164,7 +164,7 @@
Documentation and Release Notes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Release notes for the voltha-X.Y release are created and added to the voltha-docs repo. Please follow the template of
-past releases, an :doc:`example </voltha_releases/voltha_2.9>`
+past releases, an :doc:`example <voltha_releases/voltha_2.9>`
Also, if needed a voltha-X.Y branch is created on docs repo. These release notes also contain all the
versions of components that will be released, and may be updated during the final QA process.
diff --git a/release_notes/index.rst b/release_notes/index.rst
index 498fdee..829012b 100644
--- a/release_notes/index.rst
+++ b/release_notes/index.rst
@@ -15,3 +15,5 @@
voltha_2.4.rst
voltha_2.3.rst
voltha_2.2.rst
+
+ template