Merge "PDF documentation build"

This commit is contained in:
Zuul 2019-08-30 19:42:42 +00:00 committed by Gerrit Code Review
commit 78aae12a88
13 changed files with 140 additions and 58 deletions

32
doc/source/_intro.rst Normal file

@ -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!

@ -1,8 +1,8 @@
.. This file is manually generated, unlike many of the other chapters. .. 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` The :command:`neutron-debug` client is an extension to the :command:`neutron`
command-line interface (CLI) for the OpenStack neutron-debug tool. command-line interface (CLI) for the OpenStack neutron-debug tool.

@ -1,8 +1,8 @@
.. This file is manually generated, unlike many of the other chapters. .. 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 The :command:`neutron-sanity-check` client is a tool that checks various
sanity about the Networking service. sanity about the Networking service.

@ -1,8 +1,8 @@
.. This file is manually generated, unlike many of the other chapters. .. 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 The :command:`neutron-status` provides routines for checking the status of
Neutron deployment. Neutron deployment.

@ -229,7 +229,7 @@ htmlhelp_basename = 'neutrondoc'
# (source start file, target name, title, author, # (source start file, target name, title, author,
# documentclass [howto/manual]). # documentclass [howto/manual]).
latex_documents = [ latex_documents = [
('index', 'Neutron.tex', u'Neutron Documentation', ('pdf-index', 'neutron.tex', u'Neutron Documentation',
u'Neutron development team', 'manual'), u'Neutron development team', 'manual'),
] ]
@ -241,15 +241,23 @@ latex_documents = [
# not chapters. # not chapters.
#latex_use_parts = False #latex_use_parts = False
# Additional stuff for the LaTeX preamble.
#latex_preamble = ''
# Documents to append as an appendix to all manuals. # Documents to append as an appendix to all manuals.
#latex_appendices = [] #latex_appendices = []
# If false, no module index is generated. # If false, no module index is generated.
#latex_use_modindex = True #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 --------------------------------- # -- Options for oslo_config.sphinxconfiggen ---------------------------------
_config_generator_config_files = [ _config_generator_config_files = [

@ -4,10 +4,21 @@ Configuration Reference
This section provides a list of all configuration options for various neutron This section provides a list of all configuration options for various neutron
services. These are auto-generated from neutron code when this documentation is 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 is no restriction on configuration filename in neutron and you can use
arbitrary file names. arbitrary file names.
.. only:: html
For sample configuration files, refer to :doc:`config-samples`.
.. toctree::
:hidden:
config-samples
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1

@ -1,26 +1,11 @@
.. _configuring: .. _configuring:
=========================== ===================
Neutron Configuration Guide Configuration Guide
=========================== ===================
Configuration
-------------
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
config config
config-samples policy
Policy
------
Neutron, like most OpenStack projects, uses a policy language to restrict
permissions on REST API actions.
.. toctree::
:maxdepth: 1
Policy Reference <policy>
policy-sample

@ -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. 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:: .. show-policy::
:config-file: etc/oslo-policy-generator/policy.conf :config-file: etc/oslo-policy-generator/policy.conf

@ -17,22 +17,10 @@
Welcome to Neutron's documentation! Welcome to Neutron's documentation!
=================================== ===================================
Neutron is an OpenStack project to provide "network connectivity as a service" .. include:: _intro.rst
between interface devices (e.g., vNICs) managed by other OpenStack services
(e.g., nova). It implements the `Neutron API`_.
.. _`Neutron API`: https://docs.openstack.org/api-ref/network/ .. 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.
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!
Installation Guide Installation Guide
------------------ ------------------
@ -81,10 +69,11 @@ Contributor Guide
contributor/index 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 Search
------ ------

@ -1,8 +1,8 @@
.. _networking: .. _networking:
================== =====================================
Networking service Networking service Installation Guide
================== =====================================
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1

30
doc/source/pdf-index.rst Normal file

@ -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

@ -0,0 +1,6 @@
=============
API Reference
=============
The reference of the OpenStack networking API is found at
https://docs.openstack.org/api-ref/network/.

10
tox.ini

@ -149,6 +149,16 @@ envdir = {toxworkdir}/docs
deps = -r{toxinidir}/doc/requirements.txt deps = -r{toxinidir}/doc/requirements.txt
commands = sphinx-build -W -b html doc/source doc/build/html 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] [testenv:linkcheck]
basepython = python3 basepython = python3
envdir = {toxworkdir}/docs envdir = {toxworkdir}/docs