From 38d53da1881f7fa871a89d24e2eaff096c0996d5 Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Thu, 22 Mar 2018 15:20:21 +0900 Subject: [PATCH] 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 | 1 + doc/source/_static/.placeholder | 0 doc/source/admin/index.rst | 14 ++++++++ doc/source/conf.py | 25 ++++++++++++- doc/source/configuration/index.rst | 30 ++++++++++++++++ doc/source/configuration/l3_agent.rst | 6 ++++ doc/source/configuration/neutron_vpnaas.rst | 6 ++++ doc/source/configuration/samples/l3_agent.rst | 8 +++++ .../configuration/samples/neutron_vpnaas.rst | 8 +++++ doc/source/contributor/index.rst | 11 ++---- doc/source/index.rst | 36 +++++++++---------- doc/source/install/index.rst | 10 ++++++ doc/source/user/index.rst | 10 ++++++ .../{vpn_agent.ini => l3_agent.ini} | 2 +- tox.ini | 2 +- 15 files changed, 138 insertions(+), 31 deletions(-) create mode 100644 doc/source/_static/.placeholder create mode 100644 doc/source/admin/index.rst create mode 100644 doc/source/configuration/index.rst create mode 100644 doc/source/configuration/l3_agent.rst create mode 100644 doc/source/configuration/neutron_vpnaas.rst create mode 100644 doc/source/configuration/samples/l3_agent.rst create mode 100644 doc/source/configuration/samples/neutron_vpnaas.rst create mode 100644 doc/source/install/index.rst create mode 100644 doc/source/user/index.rst rename etc/oslo-config-generator/{vpn_agent.ini => l3_agent.ini} (60%) diff --git a/.gitignore b/.gitignore index 2aeb83d07..3b667ce67 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ cover/ covhtml/ dist/ doc/build +doc/source/_static/config_samples/*.sample etc/*.sample *.DS_Store *.pyc diff --git a/doc/source/_static/.placeholder b/doc/source/_static/.placeholder new file mode 100644 index 000000000..e69de29bb diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst new file mode 100644 index 000000000..4f7651c76 --- /dev/null +++ b/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. diff --git a/doc/source/conf.py b/doc/source/conf.py index f7fd6a87f..c5449ec05 100644 --- a/doc/source/conf.py +++ b/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 +] diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 000000000..f4cf9d75f --- /dev/null +++ b/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/* diff --git a/doc/source/configuration/l3_agent.rst b/doc/source/configuration/l3_agent.rst new file mode 100644 index 000000000..6bb8bd388 --- /dev/null +++ b/doc/source/configuration/l3_agent.rst @@ -0,0 +1,6 @@ +============ +l3_agent.ini +============ + +.. show-options:: + :config-file: etc/oslo-config-generator/l3_agent.ini diff --git a/doc/source/configuration/neutron_vpnaas.rst b/doc/source/configuration/neutron_vpnaas.rst new file mode 100644 index 000000000..488df31be --- /dev/null +++ b/doc/source/configuration/neutron_vpnaas.rst @@ -0,0 +1,6 @@ +=================== +neutron_vpnaas.conf +=================== + +.. show-options:: + :config-file: etc/oslo-config-generator/neutron_vpnaas.conf diff --git a/doc/source/configuration/samples/l3_agent.rst b/doc/source/configuration/samples/l3_agent.rst new file mode 100644 index 000000000..5533384ed --- /dev/null +++ b/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 diff --git a/doc/source/configuration/samples/neutron_vpnaas.rst b/doc/source/configuration/samples/neutron_vpnaas.rst new file mode 100644 index 000000000..d9e9fdd03 --- /dev/null +++ b/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 diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 5268d8abd..5d5a8fc8f 100644 --- a/doc/source/contributor/index.rst +++ b/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` diff --git a/doc/source/index.rst b/doc/source/index.rst index 98ab5adcb..18d4e4877 100644 --- a/doc/source/index.rst +++ b/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 + Release Notes - 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` diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 000000000..74772bd6e --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,10 @@ +============ +Installation +============ + +The detail instruction to enable neutron VPNaaS is described in +`the Networking Guide +`__. +Follow the instruction after installing ``neutron-vpnaas`` from distributor +packages or PyPI. + diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 000000000..abc7996d4 --- /dev/null +++ b/doc/source/user/index.rst @@ -0,0 +1,10 @@ +========== +User Guide +========== + +Basic Usage +----------- + +The basic scenarios are explained in +`the Networking Guide +`__. diff --git a/etc/oslo-config-generator/vpn_agent.ini b/etc/oslo-config-generator/l3_agent.ini similarity index 60% rename from etc/oslo-config-generator/vpn_agent.ini rename to etc/oslo-config-generator/l3_agent.ini index 875202cee..f58b86a83 100644 --- a/etc/oslo-config-generator/vpn_agent.ini +++ b/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 diff --git a/tox.ini b/tox.ini index e347b1bcd..01136f5aa 100644 --- a/tox.ini +++ b/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