diff --git a/doc/source/_intro.rst b/doc/source/_intro.rst new file mode 100644 index 00000000000..8f907e6b97a --- /dev/null +++ b/doc/source/_intro.rst @@ -0,0 +1,32 @@ +.. + Copyright 2011- OpenStack Foundation + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +Neutron is an OpenStack project to provide "network connectivity as a service" +between interface devices (e.g., vNICs) managed by other OpenStack services +(e.g., nova). It implements the `OpenStack Networking API`_. + +.. _`OpenStack Networking API`: https://docs.openstack.org/api-ref/network/ + +This documentation is generated by the Sphinx toolkit and lives in the source +tree. Additional documentation on Neutron and other components of OpenStack +can be found on the `OpenStack wiki`_ and the `Neutron section of the wiki`. +The `Neutron Development wiki`_ is also a good resource for new contributors. + +.. _`OpenStack wiki`: https://wiki.openstack.org +.. _`Neutron section of the wiki`: https://wiki.openstack.org/Neutron +.. _`Neutron Development wiki`: https://wiki.openstack.org/NeutronDevelopment + +Enjoy! diff --git a/doc/source/cli/neutron-debug.rst b/doc/source/cli/neutron-debug.rst index 857682cef16..d753cfeacbc 100644 --- a/doc/source/cli/neutron-debug.rst +++ b/doc/source/cli/neutron-debug.rst @@ -1,8 +1,8 @@ .. This file is manually generated, unlike many of the other chapters. -================================= -neutron-debug command-line client -================================= +============= +neutron-debug +============= The :command:`neutron-debug` client is an extension to the :command:`neutron` command-line interface (CLI) for the OpenStack neutron-debug tool. diff --git a/doc/source/cli/neutron-sanity-check.rst b/doc/source/cli/neutron-sanity-check.rst index 858fd316dcf..ebe3beef565 100644 --- a/doc/source/cli/neutron-sanity-check.rst +++ b/doc/source/cli/neutron-sanity-check.rst @@ -1,8 +1,8 @@ .. This file is manually generated, unlike many of the other chapters. -======================================== -neutron-sanity-check command-line client -======================================== +==================== +neutron-sanity-check +==================== The :command:`neutron-sanity-check` client is a tool that checks various sanity about the Networking service. diff --git a/doc/source/cli/neutron-status.rst b/doc/source/cli/neutron-status.rst index 81486bb716a..6b2c1684e8b 100644 --- a/doc/source/cli/neutron-status.rst +++ b/doc/source/cli/neutron-status.rst @@ -1,8 +1,8 @@ .. This file is manually generated, unlike many of the other chapters. -================================== -neutron-status command-line client -================================== +============== +neutron-status +============== The :command:`neutron-status` provides routines for checking the status of Neutron deployment. diff --git a/doc/source/conf.py b/doc/source/conf.py index c6ce1eb2b1c..850b8d10fb6 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -235,7 +235,7 @@ htmlhelp_basename = 'neutrondoc' # (source start file, target name, title, author, # documentclass [howto/manual]). latex_documents = [ - ('index', 'Neutron.tex', u'Neutron Documentation', + ('pdf-index', 'neutron.tex', u'Neutron Documentation', u'Neutron development team', 'manual'), ] @@ -247,15 +247,23 @@ latex_documents = [ # not chapters. #latex_use_parts = False -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - # Documents to append as an appendix to all manuals. #latex_appendices = [] # If false, no module index is generated. #latex_use_modindex = True +# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664 +latex_use_xindy = False + +latex_domain_indices = False + +latex_elements = { + 'makeindex': '', + 'printindex': '', + 'preamble': r'\setcounter{tocdepth}{3}', +} + # -- Options for oslo_config.sphinxconfiggen --------------------------------- _config_generator_config_files = [ diff --git a/doc/source/configuration/config.rst b/doc/source/configuration/config.rst index 062a1b722e4..3d8b3b7c3e9 100644 --- a/doc/source/configuration/config.rst +++ b/doc/source/configuration/config.rst @@ -4,10 +4,21 @@ Configuration Reference This section provides a list of all configuration options for various neutron services. These are auto-generated from neutron code when this documentation is -built. Configuration filenames used below are filenames usually used, but there +built. + +Configuration filenames used below are filenames usually used, but there is no restriction on configuration filename in neutron and you can use arbitrary file names. +.. only:: html + + For sample configuration files, refer to :doc:`config-samples`. + + .. toctree:: + :hidden: + + config-samples + .. toctree:: :maxdepth: 1 diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index 41984e1eaa7..6d6d7f88c73 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/configuration/index.rst @@ -1,26 +1,11 @@ .. _configuring: -=========================== -Neutron Configuration Guide -=========================== - -Configuration -------------- +=================== +Configuration Guide +=================== .. toctree:: :maxdepth: 1 config - config-samples - -Policy ------- - -Neutron, like most OpenStack projects, uses a policy language to restrict -permissions on REST API actions. - -.. toctree:: - :maxdepth: 1 - - Policy Reference - policy-sample + policy diff --git a/doc/source/configuration/policy.rst b/doc/source/configuration/policy.rst index 8d754b7fb22..8ee5872d627 100644 --- a/doc/source/configuration/policy.rst +++ b/doc/source/configuration/policy.rst @@ -1,9 +1,20 @@ -======================== -Neutron Policy Reference -======================== +================ +Policy Reference +================ + +Neutron, like most OpenStack projects, uses a policy language to restrict +permissions on REST API actions. The following is an overview of all available policies in neutron. -For a sample configuration file, refer to :doc:`/configuration/policy-sample`. + +.. only:: html + + For a sample policy file, refer to :doc:`/configuration/policy-sample`. + + .. toctree:: + :hidden: + + policy-sample .. show-policy:: :config-file: etc/oslo-policy-generator/policy.conf diff --git a/doc/source/index.rst b/doc/source/index.rst index ffd7cd73c6a..74bb20d9094 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -17,22 +17,10 @@ Welcome to Neutron's documentation! =================================== -Neutron is an OpenStack project to provide "network connectivity as a service" -between interface devices (e.g., vNICs) managed by other OpenStack services -(e.g., nova). It implements the `Neutron API`_. +.. include:: _intro.rst -.. _`Neutron API`: https://docs.openstack.org/api-ref/network/ - -This documentation is generated by the Sphinx toolkit and lives in the source -tree. Additional documentation on Neutron and other components of OpenStack -can be found on the `OpenStack wiki`_ and the `Neutron section of the wiki`. -The `Neutron Development wiki`_ is also a good resource for new contributors. - -.. _`OpenStack wiki`: https://wiki.openstack.org -.. _`Neutron section of the wiki`: https://wiki.openstack.org/Neutron -.. _`Neutron Development wiki`: https://wiki.openstack.org/NeutronDevelopment - -Enjoy! +.. We use different index pages for HTML and PDF documents for better TOC. + Please ensure to update pdf-index.rst when you update the index below. Installation Guide ------------------ @@ -81,10 +69,11 @@ Contributor Guide contributor/index -API Extensions --------------- +API Reference +------------- -Go to https://docs.openstack.org/api-ref/network/ for information about the OpenStack Network API and its extensions. +Go to https://docs.openstack.org/api-ref/network/ for information +about the OpenStack Network API and its extensions. Search ------ diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 3fe68af7c25..c9e823fa362 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -1,8 +1,8 @@ .. _networking: -================== -Networking service -================== +===================================== +Networking service Installation Guide +===================================== .. toctree:: :maxdepth: 1 diff --git a/doc/source/pdf-index.rst b/doc/source/pdf-index.rst new file mode 100644 index 00000000000..a82c4185bfd --- /dev/null +++ b/doc/source/pdf-index.rst @@ -0,0 +1,30 @@ +:orphan: + +.. + Copyright 2011- OpenStack Foundation + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. include:: _intro.rst + +.. toctree:: + :maxdepth: 2 + + install/index + admin/index + configuration/index + cli/index + reference/rest-api + feature_classification/index + contributor/index diff --git a/doc/source/reference/rest-api.rst b/doc/source/reference/rest-api.rst new file mode 100644 index 00000000000..d070768d086 --- /dev/null +++ b/doc/source/reference/rest-api.rst @@ -0,0 +1,6 @@ +============= +API Reference +============= + +The reference of the OpenStack networking API is found at +https://docs.openstack.org/api-ref/network/. diff --git a/tox.ini b/tox.ini index f7c0a06fb1c..42c30c3d44e 100644 --- a/tox.ini +++ b/tox.ini @@ -149,6 +149,16 @@ envdir = {toxworkdir}/docs deps = -r{toxinidir}/doc/requirements.txt commands = sphinx-build -W -b html doc/source doc/build/html +[testenv:pdf-docs] +basepython = python3 +envdir = {toxworkdir}/docs +deps = {[testenv:docs]deps} +whitelist_externals = + make +commands = + sphinx-build -W -b latex doc/source doc/build/pdf + make -C doc/build/pdf + [testenv:linkcheck] basepython = python3 envdir = {toxworkdir}/docs