summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorTrevor Bramwell <tbramwell@linuxfoundation.org>2018-08-30 18:51:37 +0000
committerGerrit Code Review <gerrit@opnfv.org>2018-08-30 18:51:37 +0000
commitc1090621dbe5d54b8d52cfe380213bc152b3f7c5 (patch)
treebfa8bc075091d877df1a3f129862d1ce34049229
parent8165c1bdfef15ce62dcfe54ecd4698bb1725c41d (diff)
parent8f28a9846b2ec7470004f3203a1d3b380855726e (diff)
Merge "Submodule to RTD transition documentation"
-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