118 lines
4.3 KiB
ReStructuredText
118 lines
4.3 KiB
ReStructuredText
Documentation
|
|
=============
|
|
|
|
Tips for Doc Writers (and Developers, too!)
|
|
-------------------------------------------
|
|
|
|
Here are some useful tips about questions that come up a lot but aren't always
|
|
easy to find answers to.
|
|
|
|
* Make example URLs consistent
|
|
|
|
For consistency, example URLs for openstack components are in the form:
|
|
|
|
.. code::
|
|
|
|
project.openstack.example.org
|
|
|
|
So, for example, an example image-list call to Glance would use a URL
|
|
written like this:
|
|
|
|
.. code::
|
|
|
|
http://glance.openstack.example.org/v2/images
|
|
|
|
Where to Contribute
|
|
-------------------
|
|
|
|
There are a few different kinds of documentation associated with Glance to
|
|
which you may want to contribute:
|
|
|
|
* Configuration
|
|
|
|
As you read through the sample configuration files in the ``etc`` directory
|
|
in the source tree, you may find typographical errors, or grammatical
|
|
problems, or text that could use clarification. The Glance team welcomes
|
|
your contributions, but please note that the sample configuration files are
|
|
generated, not static text. Thus you must modify the source code where the
|
|
particular option you're correcting is defined and then re-generate the conf
|
|
file using ``tox -e genconfig``.
|
|
|
|
* Glance's Documentation
|
|
|
|
The Glance Documentation (what you're reading right now) lives in the source
|
|
code tree under ``doc/source``. It consists of information for developers
|
|
working on Glance, information for consumers of the OpenStack Images APIs
|
|
implemented by Glance, and information for operators deploying Glance. Thus
|
|
there's a wide range of documents to which you could contribute.
|
|
|
|
Small improvements can simply be addressed by a patch, but it's probably a
|
|
good idea to first file a bug for larger changes so they can be tracked more
|
|
easily (especially if you plan to submit several different patches to address
|
|
the shortcoming).
|
|
|
|
* User Guides
|
|
|
|
There are several user guides published by the OpenStack Documentation Team.
|
|
Please see the README in their code repository for more information:
|
|
https://github.com/openstack/openstack-manuals
|
|
|
|
* OpenStack API Reference
|
|
|
|
There's a "quick reference" guide to the APIs implemented by Glance:
|
|
http://developer.openstack.org/api-ref/image/
|
|
|
|
The guide is generated from source files in the source code tree under
|
|
``api-ref/source``. Corrections in spelling or typographical errors may be
|
|
addressed directly by a patch. If you note a divergence between the API
|
|
reference and the actual behavior of Glance, please file a bug before
|
|
submitting a patch.
|
|
|
|
Additionally, now that the quick reference guides are being maintained by
|
|
each project (rather than a central team), you may note divergences in format
|
|
between the Glance guides and those of other teams. For example, some
|
|
projects may have adopted an informative new way to display error codes. If
|
|
you notice structural improvements that our API reference is missing, please
|
|
file a bug. And, of course, we would also welcome your patch implementing
|
|
the improvement!
|
|
|
|
Release Notes
|
|
-------------
|
|
|
|
Release notes are notes available for operators to get an idea what each
|
|
project has included and changed during a cycle. They may also include
|
|
various warnings and notices.
|
|
|
|
Generating release notes is done with Reno.
|
|
|
|
.. code-block:: bash
|
|
|
|
$ tox -e venv -- reno new <bug-,bp-,whatever>
|
|
|
|
This will generate a yaml file in ``releasenotes/notes`` that will contain
|
|
instructions about how to fill in (or remove) the various sections of
|
|
the document. Modify the yaml file as appropriate and include it as
|
|
part of your commit.
|
|
|
|
Commit your note to git (required for reno to pick it up):
|
|
|
|
.. code-block:: bash
|
|
|
|
$ git add releasenotes/notes/<note>; git commit
|
|
|
|
Once the release notes have been committed you can build them by using:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ tox -e releasenotes
|
|
|
|
This will create the HTML files under ``releasenotes/build/html/``.
|
|
|
|
**NOTE**: The ``prelude`` section in the release notes is to highlight only the
|
|
important changes of the release. Please word your note accordingly and be
|
|
judicious when adding content there. We don't encourage extraneous notes and at
|
|
the same time we don't want to miss out on important ones. In short, not every
|
|
release note will need content in the ``prelude`` section. If what you're
|
|
working on required a spec, then a prelude is appropriate. If you're submitting
|
|
a bugfix, most likely not; a spec-lite is a judgement call.
|