diff --git a/doc/doc-contrib-guide/source/doc-tools/scripts.rst b/doc/doc-contrib-guide/source/doc-tools/scripts.rst index bd4508aa6d..5e4b7f898a 100644 --- a/doc/doc-contrib-guide/source/doc-tools/scripts.rst +++ b/doc/doc-contrib-guide/source/doc-tools/scripts.rst @@ -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 +`_ +and `Sphinx Oslo Sample Config Generation +`_. + +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 +`_. + +cliff +~~~~~ + +The cliff framework provides a directive to document multiple commands. + +For more information, see `Sphinx Integration for cliff +`_. + +stevedore +~~~~~~~~~ + +The stevedore library provides a single directive for listing plugins for an +entrypoint. + +For more information, see `Sphinx Integration for stevedore +`_. openstack-doc-tools repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -42,7 +79,6 @@ publishdocs.sh Publishdocs job uses this script to publish documentation to https://docs.openstack.org/. - Notes ~~~~~ diff --git a/doc/doc-contrib-guide/source/project-guides.rst b/doc/doc-contrib-guide/source/project-guides.rst index 15e29ea8f5..bae8dddefa 100644 --- a/doc/doc-contrib-guide/source/project-guides.rst +++ b/doc/doc-contrib-guide/source/project-guides.rst @@ -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/`` diff --git a/doc/doc-contrib-guide/source/quickstart.rst b/doc/doc-contrib-guide/source/quickstart.rst index 6dd1cdc02e..f3d95b5492 100644 --- a/doc/doc-contrib-guide/source/quickstart.rst +++ b/doc/doc-contrib-guide/source/quickstart.rst @@ -14,4 +14,3 @@ use case. quickstart/first-timers.rst quickstart/developers.rst - quickstart/new-projects.rst diff --git a/doc/doc-contrib-guide/source/quickstart/developers.rst b/doc/doc-contrib-guide/source/quickstart/developers.rst index 2b8e317871..9af9a15b20 100644 --- a/doc/doc-contrib-guide/source/quickstart/developers.rst +++ b/doc/doc-contrib-guide/source/quickstart/developers.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. diff --git a/doc/doc-contrib-guide/source/quickstart/new-projects.rst b/doc/doc-contrib-guide/source/quickstart/new-projects.rst deleted file mode 100644 index 3da8c8c137..0000000000 --- a/doc/doc-contrib-guide/source/quickstart/new-projects.rst +++ /dev/null @@ -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`. diff --git a/doc/doc-contrib-guide/source/vendor-drivers.rst b/doc/doc-contrib-guide/source/vendor-drivers.rst deleted file mode 100644 index 2cfcf461f8..0000000000 --- a/doc/doc-contrib-guide/source/vendor-drivers.rst +++ /dev/null @@ -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 `_ -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. diff --git a/doc/doc-contrib-guide/source/writing-docs.rst b/doc/doc-contrib-guide/source/writing-docs.rst index 3dd11ad044..8a95f6ce47 100644 --- a/doc/doc-contrib-guide/source/writing-docs.rst +++ b/doc/doc-contrib-guide/source/writing-docs.rst @@ -21,4 +21,3 @@ to determine if your change renders properly. topic-structure.rst topic-tags.rst additional-git-workflow.rst - vendor-drivers.rst