git clone https://git.opendaylight.org/gerrit/docs
cd docs
git submodule update --init
- tox -edocs
+ tox
firefox docs/_build/html/index.html
-.. note:: Make sure to run `tox -edocs` and not just `tox`. See `Make
- sure you run tox -edocs`_
-
Directory Structure
-------------------
.. note:: When including rst files using ``toctree`` omit the .rst at
the end of the file name.
+Adding a submodule
+^^^^^^^^^^^^^^^^^^
+
+If you want to import a project underneath the documentation project so
+that the docs can be kept in the separate repo, you can do it using the
+``git submodule add`` command as follows::
+
+ git submodule add -b master ../integration/packaging docs/submodules/integration/packaging
+ git commit -s
+
+.. note:: Most projects will not want to use ``-b master``, but instead
+ use the branch ``.``, which will make track whatever branch
+ of the documentation project you happen to be on.
+
+ Unfortunately, ``-b .`` doesn't work, so you have to manually
+ edit the ``.gitmodules`` file to add ``branch = .`` and then
+ commit it. Something like::
+
+ <edit the .gitmodules file>
+ git add .gitmodules
+ git commit --amend
+
+When you're done you should have a git commit something like::
+
+ $ git show
+ commit 7943ce2cb41cd9d36ce93ee9003510ce3edd7fa9
+ Author: Daniel Farrell <dfarrell@redhat.com>
+ Date: Fri Dec 23 14:45:44 2016 -0500
+
+ Add Int/Pack to git submodules for RTD generation
+
+ Change-Id: I64cd36ca044b8303cb7fc465b2d91470819a9fe6
+ Signed-off-by: Daniel Farrell <dfarrell@redhat.com>
+
+ diff --git a/.gitmodules b/.gitmodules
+ index 91201bf6..b56e11c8 100644
+ --- a/.gitmodules
+ +++ b/.gitmodules
+ @@ -38,3 +38,7 @@
+ path = docs/submodules/ovsdb
+ url = ../ovsdb
+ branch = .
+ +[submodule "docs/submodules/integration/packaging"]
+ + path = docs/submodules/integration/packaging
+ + url = ../integration/packaging
+ + branch = master
+ diff --git a/docs/submodules/integration/packaging b/docs/submodules/integration/packaging
+ new file mode 160000
+ index 00000000..fd5a8185
+ --- /dev/null
+ +++ b/docs/submodules/integration/packaging
+ @@ -0,0 +1 @@
+ +Subproject commit fd5a81853e71d45945471d0f91bbdac1a1444386
+
+As usual, you can push it to Gerrit with ``git review``.
+
+.. important:: It's critical that the Gerrit patch be merged before the
+ git commit hash of the submodule changes. Otherwise,
+ Gerrit won't be able to automatically keep it up-to-date
+ for you.
+
Documentation Layout and Style
------------------------------
in the submodules. This should only be the case if you
manually edited files in that directory.
-Make sure you run tox -edocs
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you see an error like::
-
- ERROR: docs: could not install deps [-rrequirements.txt]; v = InvocationError('/Users/ckd/git-reps/docs/.tox/docs/bin/pip install -rrequirements.txt (see /Users/ckd/git-reps/docs/.tox/docs/log/docs-1.log)', 1)
- ERROR: docs-linkcheck: could not install deps [-rrequirements.txt]; v = InvocationError('/Users/ckd/git-reps/docs/.tox/docs-linkcheck/bin/pip install -rrequirements.txt (see /Users/ckd/git-reps/docs/.tox/docs-linkcheck/log/docs-linkcheck-1.log)', 1)
-
-It usually means you ran `tox` and not `tox -edocs`, which will result
-in running jobs inside submodules which aren't supported by the
-environment defined by the `requirements.txt` file in the documentation
-tox setup. Just run tox -edocs and it should be fine.
-
Clear your tox directory and try again
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
directory and building again::
rm -rf .tox
- tox -edocs
+ tox
Builds on Read the Docs
^^^^^^^^^^^^^^^^^^^^^^^
taking too long by removing directories of generated javadoc that were
present from previous runs.
+Weird Errors from Coala
+^^^^^^^^^^^^^^^^^^^^^^^
+
+As pat of running ``tox``, two environments run: ``coala`` which does a variety
+of reStructuredText_ (and other) linting, and ``docs``, which runs Sphinx_ to
+build HTML and PDF documentation. You can run them independently by doing
+``tox -ecoala`` or ``tox -edocs``.
+
+The ``coala`` linter for reStructuredText isn't always the most helpful in
+explaining why it failed. So, here are some common ones. There should also be
+Jenkins Failure Cause Management rules that will highlight these for you.
+
+Git Commit Message Errors
+"""""""""""""""""""""""""
+
+Coala will check git commit messages for a variety of things including
+
+* Shortlog (1st line of commit message) is less than 50 characters
+* Shortlog (1st line of commit message) is in the imperative mood, e.g., "Add
+ foo unit test" is good, but "Adding foo unit test is bad""
+* Body (all lines but 1st line of commit message) are less than 72 characters.
+ Some exceptions seem to exist, e.g., for long URLs.
+
+Some examples of those being logged are:
+
+::
+ Project wide:
+ | | [NORMAL] GitCommitBear:
+ | | Shortlog of HEAD commit isn't in imperative mood! Bad words are 'Adding'
+
+::
+ Project wide:
+ | | [NORMAL] GitCommitBear:
+ | | Body of HEAD commit contains too long lines. Commit body lines should not exceed 72 characters.
+
+Error in "code-block" directive
+"""""""""""""""""""""""""""""""
+
+If you see an error like this:
+
+::
+ docs/gerrit.rst
+ | 89| ···..·code-block::·bash
+ | | [MAJOR] RSTcheckBear:
+ | | (ERROR/3) Error in "code-block" directive:
+
+It seems to mean that the relevant code-block does is not valid for the
+language specified, in this case bash. Note that if you specify no language, it
+seems as though it assumes the language is python. If you want the code-block
+to not be an any particular language, instead use the ``::`` directive. For
+example:
+
+::
+ ::
+ This is a code block
+ that will not be parsed
+ in any particluar langauge
+
Project Documentation Requirements
==================================
#. Make sure the documentation project still builds.
- * Run ``tox -edocs`` from the root of the cloned docs repo.
+ * Run ``tox`` from the root of the cloned docs repo.
* After that, you should be able to find the HTML version of the
docs at ``docs.git/docs/_build/html/index.html``.
Code Review / docs.git / blobdiff