[contrib] Remove unneeded or outdated content, document more tools
Change-Id: I814736749786eedfd02574328575f43eaf5bb6b3
This commit is contained in:
Petr Kovar
parent
4c5d3e6d59
commit
157bb9bef2
@ -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
|
||||
~~~~~
|
||||
|
||||
|
||||
@ -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/``
|
||||
|
||||
|
||||
@ -14,4 +14,3 @@ use case.
|
||||
|
||||
quickstart/first-timers.rst
|
||||
quickstart/developers.rst
|
||||
quickstart/new-projects.rst
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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`.
|
||||
@ -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.
|
||||
@ -21,4 +21,3 @@ to determine if your change renders properly.
|
||||
topic-structure.rst
|
||||
topic-tags.rst
|
||||
additional-git-workflow.rst
|
||||
vendor-drivers.rst
|
||||
|
||||
Loading…
Reference in New Issue
Block a user