Contributing Documentation to Skyline APIServer
===============================================

This page provides guidance on how to provide documentation for those
who may not have previously been active writing documentation for
OpenStack.

Documentation Content
---------------------

To keep the documentation consistent across projects, and to maintain
quality, please follow the OpenStack `Writing style
<https://docs.openstack.org/doc-contrib-guide/writing-style.html>`_
guide.

Using RST
---------

OpenStack documentation uses reStructuredText to write documentation.
The files end with a ``.rst`` extension.  The ``.rst`` files are then
processed by Sphinx to build HTML based on the RST files.

.. note::
   Files that are to be included using the ``.. include::`` directive in an
   RST file should use the ``.inc`` extension.  If you instead use the ``.rst``
   this will result in the RST file being processed twice during the build and
   cause Sphinx to generate a warning during the build.

reStructuredText is a powerful language for generating web pages.  The
documentation team has put together an `RST conventions`_ page with information
and links related to RST.

.. _RST conventions: https://docs.openstack.org/doc-contrib-guide/rst-conv.html

Building Skyline APIServer's Documentation
------------------------------------------

To build documentation the following command should be used:

.. code-block:: console

   tox -e docs

When building documentation it is important to also run docs.

.. note::

   The tox documentation jobs (docs, releasenotes) are set up to treat Sphinx
   warnings as errors.  This is because many Sphinx warnings result in
   improperly formatted pages being generated, so we prefer to fix those right
   now, instead of waiting for someone to report a docs bug.

During the documentation build a number of things happen:

* All of the RST files under ``doc/source`` are processed and built.

  * The openstackdocs theme is applied to all of the files so that they
    will look consistent with all the other OpenStack documentation.
  * The resulting HTML is put into ``doc/build/html``.

* All of Skyline APIServer's ``.py`` files are processed and the docstrings are
  used to generate the files under ``doc/source/contributor/api``

After the build completes the results may be accessed via a web browser in
the ``doc/build/html`` directory structure.

Review and Release Process
--------------------------
Documentation changes go through the same review process as all other changes.

.. note::

   Reviewers can see the resulting web page output by clicking on
   ``openstack-tox-docs`` in the "Zuul check" table on the review,
   and then look for "Artifacts" > "Docs preview site".

   This is also true for the ``build-openstack-releasenotes`` check jobs.

Once a patch is approved it is immediately released to the docs.openstack.org
website and can be seen under Skyline APIServer's Documentation Page at
https://docs.openstack.org/skyline-apiserver/latest\ .  When a new release is
cut a snapshot of that documentation will be kept at
``https://docs.openstack.org/skyline-apiserver/<release>``.  Changes from
master can be backported to previous branches if necessary.

Finding something to contribute
-------------------------------

If you are reading the documentation and notice something incorrect or
undocumented, you can directly submit a patch following the advice set
out below.

There are also documentation bugs that other people have noticed that
you could address:

* https://bugs.launchpad.net/skyline-apiserver/+bugs?field.tag=doc

.. note::
   If you don't see a bug listed, you can also try the tag 'docs' or
   'documentation'.  We tend to use 'doc' as the appropriate tag, but
   occasionally a bug gets tagged with a variant.
