diff options
| -rw-r--r-- | docs/etc/conf.py | 8 | ||||
| -rw-r--r-- | docs/etc/requirements.txt | 1 | ||||
| -rw-r--r-- | docs/how-to-use-docs/documentation-example.rst | 19 |
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. |