openstack/openstack-manuals
Code Issues Proposed changes

[contrib] Remove unneeded or outdated content, document more tools

Browse Source 
Change-Id: I814736749786eedfd02574328575f43eaf5bb6b3
This commit is contained in:
Petr Kovar 2018-02-14 18:51:36 +01:00
parent 4c5d3e6d59
commit 157bb9bef2
7 changed files with 43 additions and 137 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
doc/doc-contrib-guide/source/doc-tools/scripts.rst
View File

@ -3,8 +3,45 @@ Scripts overview
================
This section provides an overview of scripts used by the OpenStack
documentation project grouped by repositories they are stored in.
documentation project, writers and developers, grouped by components they are
part of.
oslo.config
~~~~~~~~~~~
The oslo.config library provides two extensions, a configuration documentation
directive and a configuration generator hook.
For more information, see `Sphinx Integration for oslo.config
<https://docs.openstack.org/oslo.config/latest/reference/sphinxext.html>`_
and `Sphinx Oslo Sample Config Generation
<https://docs.openstack.org/oslo.config/latest/reference/sphinxconfiggen.html>`_.
oslo.policy
~~~~~~~~~~~
The oslo.policy library provides two extensions, a policy documentation
directive and a policy generator hook.
For more information, see `Sphinx Oslo Sample Policy Generation
<https://docs.openstack.org/oslo.policy/latest/user/sphinxpolicygen.html>`_.
cliff
~~~~~
The cliff framework provides a directive to document multiple commands.
For more information, see `Sphinx Integration for cliff
<https://docs.openstack.org/cliff/latest/user/sphinxext.html>`_.
stevedore
~~~~~~~~~
The stevedore library provides a single directive for listing plugins for an
entrypoint.
For more information, see `Sphinx Integration for stevedore
<https://docs.openstack.org/stevedore/latest/user/sphinxext.html>`_.
openstack-doc-tools repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -42,7 +79,6 @@ publishdocs.sh
Publishdocs job uses this script to publish documentation to
https://docs.openstack.org/.
Notes
~~~~~

2
doc/doc-contrib-guide/source/project-guides.rst
View File

@ -14,7 +14,7 @@ high-level groupings that have evolved over the last years.
Within each top-level directory, project teams are free to organize
their content however seems most appropriate to them.
This is the proposed layout for phase 1 (pike):
This is the layout implemented in Pike and later:
* ``doc/source/``

1
doc/doc-contrib-guide/source/quickstart.rst
View File

@ -14,4 +14,3 @@ use case.
quickstart/first-timers.rst
quickstart/developers.rst
quickstart/new-projects.rst

10
doc/doc-contrib-guide/source/quickstart/developers.rst
View File

@ -9,10 +9,10 @@ important that you also document that new feature.
This is also true if you are adding or changing configuration options,
commands, or other user-facing components.
Many of these types of changes are handled automatically by
``openstack-doc-tools``, and published to the Configuration Reference
and Command-Line Reference. For more information about these automated
tools, see the :ref:`doc-tools` chapter.
Many of these types of changes are handled automatically by directives and
configuration generators provided by libraries such as oslo.config and
oslo.policy, and published as part of the project-specific documentation.
For more information about these automated tools, see :ref:`doc-tools`.
If you are contributing documentation to the main openstack-manuals
repository, there are a few things you can do to help your patch merge
@ -41,7 +41,5 @@ quickly and easily:
ask you to create a blueprint and specification for the change. If you are
unsure whether your change will require a blueprint or specification, ask
on the mailing list for guidance.
* If you want to create a new Installation Guide for your big tent
project, see :doc:`../project-install-guide`.
* Remember, you can always contact the documentation team through our mailing
list, or on IRC.

24
doc/doc-contrib-guide/source/quickstart/new-projects.rst
View File

@ -1,24 +0,0 @@
.. _new_projects:
============
New projects
============
If you are maintaining a new project that has recently been accepted into the
OpenStack 'big tent' then you will require some documentation for your
project.
Documentation for your project should live in your project's
git repository, and be published to `docs.openstack.org/yourproject`.
If you need to create that index page, you will also need to add the
``openstack-unified-publish-jobs`` to the appropriate repositories by
updating the settings in the ``project-config`` repository so that the
documentation is re-published with every commit.
Any configuration options or command line tools should be documented using
the automated ``openstack-doc-tools``. For more information about these
automated tools, see the :ref:`doc-tools` chapter.
To create an Installation Guide in accordance with the OpenStack
Foundation Project Navigator, follow the instructions at
:ref:`project-install-guide`.

102
doc/doc-contrib-guide/source/vendor-drivers.rst
View File

@ -1,102 +0,0 @@
=======================
Proprietary driver docs
=======================
.. important::
This documentation only applies to the released documents prior
to Pike since the content is now part of the project team repositories.
Many OpenStack projects include drivers to support specific hardware or
software. Examples are:
* Cinder: block storage drivers
* Neutron: network plug-ins
* Nova: hypervisors
* Trove: different databases
The documentation team documents the following reference drivers in the
Configuration Reference Guide:
* For cinder: volume drivers - document LVM and NFS, backup drivers - document
swift
* For glance: document local storage, cinder, and swift as back ends
* For neutron: document ML2 plug-in with the mechanisms drivers Open vSwitch
and Linux bridge
* For nova: document KVM (mostly), send Xen open source call for help
* For sahara: Apache Hadoop
* For trove: document all supported Open Source database engines like MySQL.
If a vendor wants to document their driver, they are invited - but not forced -
to include their documentation in the Configuration Reference if they commit
to maintain the documentation.
.. important::
Other documentation (including the Administrator Guide and Networking
Guide) will not contain content for third-party drivers. In these books,
where third party drivers exist, add the statement:
“For other drivers, see Chapter X in the Configuration Reference Guide”.
Guidelines
~~~~~~~~~~
The following are guidelines for drivers documented by the OpenStack community:
* The complete solution must be open source and use standard hardware
* The driver must be part of the respective OpenStack repository
* The driver is considered one of the reference drivers
For documentation of other drivers, the following guidelines apply:
* The Configuration Reference contains a small section for each driver,
see below for details.
* Only drivers are covered that are contained in the official OpenStack
project repository for drivers (for example in the main project repository or
the official third-party repository).
If a vendor wants to add more than the minimal documentation, they need to
commit to the following guidelines:
* Assign an editor that is responsible for the content.
* Review and, if necessary, update their driver for each release cycle.
Default section format for external drivers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For each external driver, the driver is briefly documented in a way that
is version independent and includes the current configuration options.
Each section should follow this format:
* A short paragraph explaining the driver.
* A link with detailed instructions to the vendor site (if there is one).
* A default paragraph, for example:
.. code-block:: rst
Set the following in your ``cinder.conf``, and use the following options
to configure it.
volume_driver = cinder.volume.drivers.smbfs.SmbfsDriver
* And finally, the autogenerated configuration options.
Driver vendors can send in patches for these, or create bugs.
Full documentation by vendors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If a vendor wants full documentation in the Configuration Reference, they
have to add to the `wiki page <https://wiki.openstack.org/wiki/Documentation/VendorDrivers>`_
a contact editor that will take care of the
vendor driver documentation. The Documentation team will assign bugs to the
contact person, include the contact person in reviews for the vendor driver,
and expects timely responses.
If vendor driver documentation becomes outdated and the contact person is not
reacting to requests, the Documentation team will change the full documentation
to a minimal version.
The documentation team will review vendor drivers and ensure that the various
driver documents follow a consistent standard.

1
doc/doc-contrib-guide/source/writing-docs.rst
View File

@ -21,4 +21,3 @@ to determine if your change renders properly.
topic-structure.rst
topic-tags.rst
additional-git-workflow.rst
vendor-drivers.rst