|
|
| Line 1: |
Line 1: |
| − | {{OpenStack_Documentation_Navbar}}
| + | The content is now available at [http://docs.openstack.org/contributor-guide/docs-structure.html the Documentation Contributor Guide]. |
| − | {{OpenStack_Conventions_Navbar}}
| |
| − | | |
| − | This page handles the structure of books - how to name and arrange files and directories.
| |
| − | | |
| − | __TOC__
| |
| − | | |
| − | == 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.
| |
| − | ----
| |
| − | [[Category:Documentation]]
| |
