docs: add process to request new sphinx extension(s)

http://lists.opnfv.org/pipermail/opnfv-tech-discuss/2015-December/006901.html

Change-Id: I3a2691bd1d69b5c8c250aaec34e4b76e28e7df73
Signed-off-by: Ryota MIBU <r-mibu@cq.jp.nec.com>
Co-Authored-By: Ildiko Vancsa <ildiko.vancsa@ericsson.com>

diff --git a/docs/etc/conf.py b/docs/etc/conf.py
index 06ae7be..d10868d 100644 (file)
--- a/docs/etc/conf.py
+++ b/docs/etc/conf.py
@@ -6,7 +6,13 @@ directory (e.g. docs/how-to-use-docs/conf.py). If there is no 'conf.py'
 in the document directory, this file will be copied to that directory
 before the document builder jobs ('opnfv-docs-verify' and 'opnfv-docs-merge').
 
 in the document directory, this file will be copied to that directory
 before the document builder jobs ('opnfv-docs-verify' and 'opnfv-docs-merge').
 

-See https://wiki.opnfv.org/documentation/tools .
+You may need python package installation for new sphinx extension.
+Install python package with 'pip' in your machine and add the extension to
+the 'extensions' list below to test the documentation build locally.
+If you feel that your extensions would be useful for other projects too,
+we encourage you to propose a change in the releng repository.
+
+For further guidance see the https://wiki.opnfv.org/documentation/tools page.

 '''
 
 extensions = ['sphinxcontrib.httpdomain']
 '''
 
 extensions = ['sphinxcontrib.httpdomain']

diff --git a/docs/etc/requirements.txt b/docs/etc/requirements.txt
new file mode 100644 (file)
index 0000000..4df3b68
--- /dev/null
+++ b/docs/etc/requirements.txt
@@ -0,0 +1 @@
+sphinxcontrib-httpdomain

diff --git a/docs/how-to-use-docs/documentation-example.rst b/docs/how-to-use-docs/documentation-example.rst
index 5fc2b14..628162b 100644 (file)
--- a/docs/how-to-use-docs/documentation-example.rst
+++ b/docs/how-to-use-docs/documentation-example.rst
@@ -87,9 +87,9 @@ If you need to change the default configuration for document build, create
 new conf.py in the document directory (e.g. 'docs/how-to-use-docs/conf.py')
 that will be used in build process instead of default for OPNFV document
 build. The OPNFV default configuration can be found in releng repo
 new conf.py in the document directory (e.g. 'docs/how-to-use-docs/conf.py')
 that will be used in build process instead of default for OPNFV document
 build. The OPNFV default configuration can be found in releng repo

-(see `conf.py`_).
+(see `docs/etc/conf.py`_).

 
 

-.. _conf.py:
+.. _docs/etc/conf.py:

     https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=docs/etc/conf.py;
 
 In the build process, the following parameters are automatically added if they
     https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=docs/etc/conf.py;
 
 In the build process, the following parameters are automatically added if they


@@ -170,3 +170,18 @@ change. Then, the merge job will upload latest build documents to
 ``http://artifacts.opnfv.org/<Project Name>/docs/`` .
 You can put links in your project wiki page, so that everyone can see the
 latest document always.
 ``http://artifacts.opnfv.org/<Project Name>/docs/`` .
 You can put links in your project wiki page, so that everyone can see the
 latest document always.

+
+Sphinx Extensions
+=================
+
+You can see available sphinx extension(s) in `docs/etc/requirements.txt`_.
+
+.. _docs/etc/requirements.txt:
+    https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=docs/etc/requirements.txt;
+
+You can use other sphinx extensions to improve your documents.
+To share such tips, we encourage you to enable the extension in OPNFV infra
+by asking releng and opnfvdocs teams to add new sphinx extension via gerrit
+(proposing change in `docs/etc/conf.py`_ and `docs/etc/requirements.txt`_).
+After quick sanity checks, we'll install python package (if needed) and make
+it available in OPNFV document build.