Jump to: navigation, search

Difference between revisions of "Documentation/Structure"

(Book check list)
(Replaced content with "The content is now available at [http://docs.openstack.org/contributor-guide/docs-structure.html the Documentation Contributor Guide].")
Line 1: Line 1:
The content is now available at [http://docs.openstack.org/contributor-guide/docs-structure.html the Documentation Contributor Guide].
This page handles the structure of books - how to name and arrange files and directories.
== Source file names ==
For XML file names, we have used prefixes like bk_, ch_, section_, and app_ at the beginning of the file name to indicate the type of file it is in the hierarchy of the build. However, in migrating to RST/Sphinx we are using the xml:id for the file name and moving towards a page-based, topical approach to file naming.  RST files should use a hyphen as the space delimiter and have the .rst extension.
== Directory structure ==
For further organization, you can use subdirectories to organize the files by a particular grouping such as project or topic.
Common practice are:
* A figures subdirectory that includes all images (both SVG source and PNG).
* A samples subdirectory that contains source code samples or configuration file samples.
* A subdirectory per chapter where all sections are in the subdirectory, the ch_ file itself is in the top level directory.
== Book check list ==
Use the following check list for books:
{| class="wikitable"
! Task !! Description !! Complete?
| pom.xml file || Your pom.xml file uses the latest (non-SNAPSHOT) cloud-doc plugin version and is configured correctly. To find the version number of the latest plugin, go to [https://github.com/rackerlabs/clouddocs-maven-plugin#release-notes Clouddocs Maven Plugin Release Notes].  ||
| TOC || Your pom.xml file configures a TOC for your book. ||
| Glossary || Embed the shared glossary and mark terms with the <glossterm> tag in your document. ||
| Preface || Your book has a preface. ||
| Doc history || The preface includes the doc history. Also make sure that you have included a revision entry for your latest changes. ||
| Title || Title is correct. ||
| Code samples || Code samples are in separate files and included in chapter, section, or appendix file. ||
| Chunking || Chapters and appendices are in separate files and included in the book file. ||
| Source file names || Source file names use file naming conventions. Book files = bk_*; Chapter files = ch_*; Appendix files = app_*; Section files = section_*. ||
== RST include file policy==
Include files using the ":include:" directive should be used for smaller content that is duplicated in several files (note that this is
something that should be avoided in general).
For include files, give the files the suffix ".txt" instead of the usual ".rst".
Note that when including files that use headings for section
structure, the master file needs to include it at the same level
since heading markup is not relative.
For structuring files, split them up and use a toctree to
reference the files. If files get too large, it is often a sign
that the information is not presented properly and therefore the
file should be reworked instead of split artifically in smaller
files using includes.
Files can be shared between guides as separate top-level files, like it's done for glossary and support appendix already.

Revision as of 19:04, 26 October 2015

The content is now available at the Documentation Contributor Guide.