howto/docs.voltha.org/quickstart.rst

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'