openstack/openstack-manuals
Code Issues Proposed changes
c054a422a2
openstack-manuals/doc/contributor-guide/source/docs-structure.rst
OlgaGusarenko ca7eef5204 [Contributor Guide] Documentation structure 
Converts the Documentation structure wikipage
https://wiki.openstack.org/wiki/Documentation/Structure
to RST.

PS: the RST include file policy section will be addressed in the
RST-related section

Change-Id: Id070fc447a17efd364a741223b1c60dfcb2ad1df
Implements: blueprint docs-contributor-guide
2015-09-04 17:22:53 +03:00

2.6 KiB
Raw Blame History

Documentation structure

File naming conventions

For XML filenames, to indicate the hierarchical type of files use the following prefixes:

  • bk_ for book,
  • ch_ for chapter,
  • section_ for section
  • app_ for appendix.

For RST filenames:

  • follow page-based, topical approach to file naming and do not apply any special prefixes,
  • use hyphen as a space delimiter.

When migrating XML to RST, use the xml:id attribute value from a source file as a filename for a converted file. For example, if the source XML file contains xml:id="technical_considerations_multi_site", name the newly created RST file as follows:

technical-considerations-multi-site.rst

Directory structure

For better organization, use subdirectories to organize the files by a particular grouping such as project or topic.

Common practices include:

  • Figure subdirectory includes images (both PNG and SVG source files).
  • Sample subdirectory contains samples of source code and configuration files.
  • Chapter subdirectory stores all sections included in one chapter with the parent file located in the top level directory.

Structure checklist

Use the following checklist for a DocBook manual.

DocBook manual checklist
Task Make sure that Tick if done
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 Clouddocs Maven Plugin Release Notes.
TOC Your pom.xml file configures a TOC for your book.
Glossary You embedded the shared glossary and marked terms with the <glossterm> tag in your document.
Preface Your book has a preface.
Document history The preface includes the document history. Also make sure that you have included a revision entry for your latest change.
Titles Titles correspond to the file content
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 filenames Source filenames use filename-conv.