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>

3 files changed, 25 insertions, 3 deletions

diff --git a/docs/etc/conf.py b/docs/etc/conf.py
index 06ae7be01..d10868de5 100644
--- 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').
 
-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']
diff --git a/docs/etc/requirements.txt b/docs/etc/requirements.txt
new file mode 100644
index 000000000..4df3b687d
--- /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 5fc2b1420..628162b79 100644
--- 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
-(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
@@ -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.
+
+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.