summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorTrevor Bramwell <tbramwell@linuxfoundation.org>2018-06-04 14:36:44 +0200
committerTrevor Bramwell <tbramwell@linuxfoundation.org>2018-08-03 12:14:11 -0700
commit8f28a9846b2ec7470004f3203a1d3b380855726e (patch)
treeaf6d60e9bc54851c2eb0db75b9a6f86def8200ab
parent30941c8136548e14ea5bb4486d3bea9d568c93bd (diff)
Submodule to RTD transition documentation
Adds documentation for current projects on how to migrate to using local doc builds, along with steps for new projects to setup their builds. Issue: DOCS-191 Change-Id: I1c850457dec1006199d095ad63469af1ca02a760 Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>
-rw-r--r--docs/how-to-use-docs/documentation-guide.rst2
-rw-r--r--docs/how-to-use-docs/files/conf.py1
-rw-r--r--docs/how-to-use-docs/files/conf.yaml3
-rw-r--r--docs/how-to-use-docs/files/index17
-rw-r--r--docs/how-to-use-docs/files/requirements.txt5
-rw-r--r--docs/how-to-use-docs/files/tox.ini17
-rw-r--r--docs/how-to-use-docs/index.rst1
-rw-r--r--docs/how-to-use-docs/local-build-transition.rst91
8 files changed, 136 insertions, 1 deletions
diff --git a/docs/how-to-use-docs/documentation-guide.rst b/docs/how-to-use-docs/documentation-guide.rst
index 56bf273bc..0f2c3bf02 100644
--- a/docs/how-to-use-docs/documentation-guide.rst
+++ b/docs/how-to-use-docs/documentation-guide.rst
@@ -15,7 +15,7 @@ Getting Started with Documentation for Your Project
OPNFV documentation is automated and integrated into our git & gerrit toolchains.
We use RST document templates in our repositories and automatically render to HTML and PDF versions of the documents in our artifact
-store, our WiKi is also able to integrate these rendered documents directly allowing projects to use the revision controlled documentation
+store, our Wiki is also able to integrate these rendered documents directly allowing projects to use the revision controlled documentation
process for project information, content and deliverables.
Read :ref:`this page <include-documentation>` which elaborates on how documentation is to be included within opnfvdocs.
diff --git a/docs/how-to-use-docs/files/conf.py b/docs/how-to-use-docs/files/conf.py
new file mode 100644
index 000000000..3c4453e71
--- /dev/null
+++ b/docs/how-to-use-docs/files/conf.py
@@ -0,0 +1 @@
+from docs_conf.conf import *
diff --git a/docs/how-to-use-docs/files/conf.yaml b/docs/how-to-use-docs/files/conf.yaml
new file mode 100644
index 000000000..caad28ff4
--- /dev/null
+++ b/docs/how-to-use-docs/files/conf.yaml
@@ -0,0 +1,3 @@
+---
+project_cfg: opnfv
+project: Example
diff --git a/docs/how-to-use-docs/files/index b/docs/how-to-use-docs/files/index
new file mode 100644
index 000000000..21da2ac4e
--- /dev/null
+++ b/docs/how-to-use-docs/files/index
@@ -0,0 +1,17 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _opnfv-project-foo:
+
+===
+FOO
+===
+
+.. toctree::
+ :numbered:
+ :maxdepth: 2
+
+ development
+ release
+ testing
diff --git a/docs/how-to-use-docs/files/requirements.txt b/docs/how-to-use-docs/files/requirements.txt
new file mode 100644
index 000000000..440843584
--- /dev/null
+++ b/docs/how-to-use-docs/files/requirements.txt
@@ -0,0 +1,5 @@
+lfdocs-conf
+sphinx_opnfv_theme
+# Uncomment the following line if your project uses Sphinx to document
+# HTTP APIs
+# sphinxcontrib-httpdomain
diff --git a/docs/how-to-use-docs/files/tox.ini b/docs/how-to-use-docs/files/tox.ini
new file mode 100644
index 000000000..69aa18937
--- /dev/null
+++ b/docs/how-to-use-docs/files/tox.ini
@@ -0,0 +1,17 @@
+[tox]
+minversion = 1.6
+envlist =
+ docs,
+ docs-linkcheck
+skipsdist = true
+
+[testenv:docs]
+deps = -rdocs/requirements.txt
+commands =
+ sphinx-build -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
+ echo "Generated docs available in {toxinidir}/docs/_build/html"
+whitelist_externals = echo
+
+[testenv:docs-linkcheck]
+deps = -rdocs/requirements.txt
+commands = sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck
diff --git a/docs/how-to-use-docs/index.rst b/docs/how-to-use-docs/index.rst
index 424f47189..c56ff40ce 100644
--- a/docs/how-to-use-docs/index.rst
+++ b/docs/how-to-use-docs/index.rst
@@ -9,4 +9,5 @@ Documentation Guide
documentation-guide
include-documentation
+ local-build-transition
addendum
diff --git a/docs/how-to-use-docs/local-build-transition.rst b/docs/how-to-use-docs/local-build-transition.rst
new file mode 100644
index 000000000..415afe816
--- /dev/null
+++ b/docs/how-to-use-docs/local-build-transition.rst
@@ -0,0 +1,91 @@
+Submodule Transition
+====================
+
+Moving away from submodules.
+
+At the cost of some release-time overhead, there are several benefits
+the transition provides projects:
+
+* Local builds - Projects will be able to build and view there docs
+ locally, as they would appear on the OPNFV Docs website.
+* Reduced build time - Patchset verification will only run against
+ individual projects docs, not all projects.
+* Decoupled build failures - Any error introduced to project's docs
+ would not break builds for all the other projects
+
+Steps
+-----
+
+To make the transition the following steps need to be taken across the
+project repository, releng repository and opnfvdocs repository.
+
+In your project repo:
+
+#. Add the following files:
+
+ *docs/conf.py*
+
+ .. literalinclude:: files/conf.py
+
+ *docs/conf.yaml*
+
+ .. literalinclude:: files/conf.yaml
+
+ *docs/requirements.txt*
+
+ .. literalinclude:: files/requirements.txt
+
+ *tox.ini*
+
+ .. literalinclude:: files/tox.ini
+
+ *.gitignore*
+
+ .tox/
+ docs/_build/*
+
+ *docs/index.rst*
+
+ if it doesn't exist along with other index file for directories
+ (release, development)
+
+In the releng repository:
+
+#. Follow the steps in `this guide`_ from the Linux Foundation Releng team on
+ bootstrapping a new ReadTheDocs (RTD) project.
+
+ This will ensure RTD will update each time docs patches are merged to
+ the repository.
+
+.. note: In step 4 of the guide, the file this job should be added to is:
+ **jjb/project/project-jobs.yaml**, where project is the OPNFV project.
+
+.. _`this guide`: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#bootstrap-a-new-project
+
+
+In the opnfvdocs repository:
+
+#. Add a intersphinx link to the opnfvdocs repo:
+
+ Here 'example' should be replaced with the name of your project.
+
+ .. code-block:: python
+ :name: docs/conf.py
+
+ intersphinx_mapping['example'] = ('http://opnfv-example.readthedocs.io', None)
+
+#. Ensure all references in opnfvdocs are using `:ref:` and not
+ directly specifying submodule files (No `:doc:` or 'submodules/...'
+ in `.. toctree:`)
+
+#. Remove the submodule from opnfvdocs::
+
+ diff --git a/.gitmodules b/.gitmodules
+ index 846ab245..aab01642 100644
+ --- a/.gitmodules
+ +++ b/.gitmodules
+ @@ -151,4 +150,0 @@
+ -[submodule "docs/submodules/releng"]
+ - path = docs/submodules/releng
+ - url = ../releng
+ - branch = master