1c7f556d4f
This change moves existing files, updates a few of the cross-references and paths, and fixes some formatting. It is not meant to be the final word on how the main page looks or how the other files are organized, but it gets everything roughly into shape. If the glance team wants to make changes, please do those as follow-up patches This change depends on the spec and on a feature of pbr that allows us to move where the auto-generated class reference documentation ends up in the tree. Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454 Depends-On: I2bd5652bb59cbd9c939931ba2e7db1b37d2b30bb Change-Id: I9dde267793a5913acb5b1ec028cfb66bc5189783 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
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.
|