Improve docs to follow the standard structure

neutron-vpnaas documentation needed to be updated to the document
structure recommended by the docs team.
This commits add several sections and reorganizes the existing docs.

Change-Id: Iae2704f3d0653e00c18cf1fccdbcb8b926a5b15c

.gitignore

@@ -6,6 +6,7 @@ cover/
 covhtml/
 dist/
 doc/build
+doc/source/_static/config_samples/*.sample
 etc/*.sample
 *.DS_Store
 *.pyc

doc/source/admin/index.rst

@@ -0,0 +1,14 @@
+====================
+Administration Guide
+====================
+
+VPNaaS Flavors
+--------------
+
+.. toctree::
+   :maxdepth: 3
+
+.. todo::
+
+   Info on the different Swan flavors, how they are different, and what
+   Operating Systems support them.

doc/source/conf.py

@@ -48,6 +48,8 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.ifconfig',
               'sphinx.ext.graphviz',
               'sphinx.ext.todo',
+              'oslo_config.sphinxext',
+              'oslo_config.sphinxconfiggen',
               'openstackdocstheme',]
 
 todo_include_todos = True
@@ -161,7 +163,7 @@ html_theme = 'openstackdocs'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
+html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -240,3 +242,24 @@ html_last_updated_fmt = '%Y-%m-%d %H:%M'
 repository_name = 'openstack/neutron-vpnaas'
 bug_project = 'neutron'
 bug_tag = 'doc'
+
+# -- Options for oslo_config.sphinxconfiggen ---------------------------------
+
+_config_generator_config_files = [
+    'l3_agent.ini',
+    'neutron_vpnaas.conf',
+]
+
+
+def _get_config_generator_config_definition(config_file):
+    config_file_path = '../../etc/oslo-config-generator/%s' % conf
+    # oslo_config.sphinxconfiggen appends '.conf.sample' to the filename,
+    # strip file extentension (.conf or .ini).
+    output_file_path = '_static/config_samples/%s' % conf.rsplit('.', 1)[0]
+    return (config_file_path, output_file_path)
+
+
+config_generator_config_file = [
+    _get_config_generator_config_definition(conf)
+    for conf in _config_generator_config_files
+]

doc/source/configuration/index.rst

@@ -0,0 +1,30 @@
+=====================
+Configuration Options
+=====================
+
+This section provides a list of all possible options for each
+configuration file.
+
+Configuration Reference
+-----------------------
+
+Neutron uses the following configuration files for its various services.
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   *
+
+Sample Configuration Files
+--------------------------
+
+The following are sample configuration files for all Neutron services and
+utilities. These are generated from code and reflect the current state of code
+in the Neutron repository.
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   samples/*

doc/source/configuration/l3_agent.rst

@@ -0,0 +1,6 @@
+============
+l3_agent.ini
+============
+
+.. show-options::
+   :config-file: etc/oslo-config-generator/l3_agent.ini

doc/source/configuration/neutron_vpnaas.rst

@@ -0,0 +1,6 @@
+===================
+neutron_vpnaas.conf
+===================
+
+.. show-options::
+   :config-file: etc/oslo-config-generator/neutron_vpnaas.conf

doc/source/configuration/samples/l3_agent.rst

@@ -0,0 +1,8 @@
+===================
+Sample l3_agent.ini
+===================
+
+This sample configuration can also be viewed in `the raw format
+<../../_static/config_samples/l3_agent.conf.sample>`_.
+
+.. literalinclude:: ../../_static/config_samples/l3_agent.conf.sample

doc/source/configuration/samples/neutron_vpnaas.rst

@@ -0,0 +1,8 @@
+==========================
+Sample neutron_vpnaas.conf
+==========================
+
+This sample configuration can also be viewed in `the raw format
+<../../_static/config_samples/neutron_vpnaas.conf.sample>`_.
+
+.. literalinclude:: ../../_static/config_samples/neutron_vpnaas.conf.sample

doc/source/contributor/index.rst

@@ -100,8 +100,8 @@ Module Reference
 
     Add in all the big modules as automodule indexes.
 
-About Documentation
--------------------
+About This Documentation
+------------------------
 
 This documentation is generated by the Sphinx toolkit and lives in the source
 tree.  Additional documentation on VPNaaS and other components of OpenStack
@@ -112,10 +112,3 @@ The `Neutron Development wiki`_ is also a good resource for new contributors.
 .. _`OpenStack wiki`: https://wiki.openstack.org/wiki/Main_Page
 .. _`Neutron section of the wiki`: https://wiki.openstack.org/wiki/Neutron
 .. _`Neutron Development wiki`: https://wiki.openstack.org/wiki/NeutronDevelopment
-
-Indices and tables
-------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

doc/source/index.rst

@@ -27,30 +27,28 @@ The `VPNaaS API`_ is implementation as an extension to Neutron's networking API:
 
 Enjoy!
 
-User Documentation
-------------------
-
-VPNaaS API
-~~~~~~~~~~
-
-Go to https://developer.openstack.org/api-ref/network/
-and see the VPNaaS section.
-
-VPNaaS Flavors
-~~~~~~~~~~~~~~
+Using VPNaaS
+------------
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
-.. todo::
+   install/index
+   configuration/index
+   user/index
+   admin/index
+   API reference <https://developer.openstack.org/api-ref/network/v2/index.html#vpnaas-2-0-vpn-vpnservices-ikepolicies-ipsecpolicies-endpoint-groups-ipsec-site-connections>
+   Release Notes <https://docs.openstack.org/releasenotes/neutron-vpnaas/>
 
-   Info on the different Swan flavors, how they are different, and what
-   Operating Systems support them.
-
-Contributor Guide
------------------
+For Contributors
+----------------
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    contributor/index
+
+Search
+------
+
+* :ref:`search`

doc/source/install/index.rst

@@ -0,0 +1,10 @@
+============
+Installation
+============
+
+The detail instruction to enable neutron VPNaaS is described in
+`the Networking Guide
+<https://docs.openstack.org/neutron/latest/admin/vpnaas-scenario.html#enabling-vpnaas>`__.
+Follow the instruction after installing ``neutron-vpnaas`` from distributor
+packages or PyPI.
+

doc/source/user/index.rst

@@ -0,0 +1,10 @@
+==========
+User Guide
+==========
+
+Basic Usage
+-----------
+
+The basic scenarios are explained in
+`the Networking Guide
+<https://docs.openstack.org/neutron/latest/admin/vpnaas-scenario.html#using-vpnaas-with-endpoint-group-recommended>`__.

etc/oslo-config-generator/l3_agent.ini

@@ -1,5 +1,5 @@
 [DEFAULT]
-output_file = etc/vpn_agent.ini.sample
+output_file = etc/l3_agent.ini.sample
 wrap_width = 79
 
 namespace = neutron.vpnaas.agent

tox.ini

@@ -75,7 +75,7 @@ commands =
 commands = {posargs}
 
 [testenv:docs]
-commands = sphinx-build -W -b html doc/source doc/build
+commands = sphinx-build -W -a -b html doc/source doc/build
 
 [flake8]
 # E125 continuation line does not distinguish itself from next logical line