2. Sphinx Doc

Sphinx Doc is a collection of scripts and templates to allow for simple setup, administration and output formatting of reStructuredText documents.

The focus is on providing a simple standalone README article and a book with chapters made from single README files.

It employs snippets(1) and the python package PyJsMo.

2.1. Documentation workflow

figure 2.1 shows the definitive state diagram for the documentation workflow. Some state transitions are triggered by a list of mandatory shell commands. For alternatives, e.g.,

\[\begin{split}\left\{\begin{array}{l} \mbox{touch file}\\ \mbox{sda automodule module}\\ \mbox{sda chapter add 'Chapter title'}\\ \end{array}\right.\end{split}\]

at least one command or an equivalent must be excuted. There is no exception to this reuqirement.

figure 2.1 Documentation workflow

2.2. Initialize documentation

2.2.1. New article

  • Execute:

    sda chap new 'Chapter title'
    

This is equivalent to:

  • Execute:

    snn --mode rst --key title --value 'Chapter title' README-chapter-title.txt
    

2.2.2. New book

  • Make book directory

  • cd to book directory

  • Execute:

    sda init "Book Title"
    

This creates an empty README.txt and a doc subdirectory for building the full version of a documentation book with chapters.

2.3. Documentation output formats

2.3.1. Article format

sda readme README.txt              # => README.html
sda readme --format pdf README.txt # => README.pdf

2.3.2. Book format

sda make html                      # => doc/_build/html/
sda make latexpdf                  # => doc/_build/latex/

sda view html                      # xdg-open 'doc/_build/html/index.html'
sda view pdf                       # xdg-open "$(  echo doc/_build/latex/*.aux | sed 's,\.aux$,\.pdf,;1q' )"

2.4. Update documentation template structure

  • cd to doc-directory

  • Execute:

    sda update
    

This creates a new sub-directory doc-directory with a new documentation project using the title from the main README (see figure 2.2).

figure 2.2 SphinxDoc - update template structure

Any generated files, that are not present in the directory being updated, are moved there. Files that do not differ are deleted. (see figure 2.3).

figure 2.3 SphinxDoc - compare updated files with original tree

Files that differ must be merged manually with M-x ediff-directories or kdiff3(1).

2.5. Document administration

Document administration is performed with sda, a shortcut link to sphinx-doc-admin.sh.

2.5.1. Automodule files

Add automodule documentation files for python modules to the doc directory.

sda automodule MODULE-OR-FILE ...

2.5.2. Chapters

Latest versions of the documentation have |:chapter:| symbol tags, which can be easily found with M-x symbol-tag-grep-find (usually defined as M-g).

Chapter administration entails a number of use cases:

sda chapter SUB-COMMAND

2.5.2.1. Adding a chapter

The following steps are automatically performed with:

sda chapter add topic
  • Create a new README-topic.txt:

    snn --mode rst README-topic.txt
    
  • Add a new entry to the variable CHAPTERS in doc/Makefile:

    CHAPTERS += ../README-topic.txt
    
  • Add the chapter file base topic to the toctree directive in doc/index-contents.snip:

    .. toctree::
       :maxdepth: 1
    
       topic
    

    Add a rule to .hgignore:

    ^doc/topic\.rst\.auto$
    

    Define a document reference in doc/doc_defs_standalone.inc:

    .. |chapter-topic|            replace:: document :file:`README-topic`
    

    Define a chapter reference in doc/doc_defs_combined.inc:

    .. |chapter-topic|            replace:: chapter :doc:`topic`
    

2.5.3. View processed documents

sda view FORMAT-OR-FILE

sda view html
sda view pdf

2.5.4. Command handlers for backends

2.6. Structural specification

  • reStructuredText is a markup language specification in the class of wiki markup languages. (Examples for other markup languages are HTML, TeX/LaTex, NROFF). reStructuredText is the official Python documentation markup.

  • UML is used for documenting programs. It is created from textual descriptions with PlantUML. See section 8, Unified Modeling Language for details.

  • Docutils is the reference library for translating reStructuredText markup into other formats like HTML/PDF/EPUB.

  • The document generator Sphinx extends Docutils and the reStructuredText specification with roles and directives. There are also various extensions to integrate other markup specifications (e.g. PlantUML, Pygments for highlighting). See section 10, Sphinx Documentation Generator for further details .

    The program sphinx-build(1) generates HTML/PDF/EPUB documentation from reStructuredText documents and doc strings of python(1) modules. It is also used in the command sda readme (sphinx-readme.sh) to generate standalone HTML/PDF/EPUB from a single README file.

2.6.1. README chapters

2.6.2. README snippets

2.7. How to properly move chapter files and sections

2.7.1. Rename chapter file in same document directory

  • Move README-chapter-old.txt to README-chapter-new.txt.

  • Execute M-x grep-find RET chapter-old RET.
    Rename info for chapter-old to info for chapter-new.
  • Clean + compile doc-new.
    Analyze error messages and correct errors.

2.7.2. Move chapter file to other document directory

  • Move README-chapter-old.txt from doc-old to README-chapter-new.txt in doc-new.

  • Execute M-x grep-find RET chapter-old RET in doc-old.
    Keep document references from doc/doc_def_standalone.inc in doc/doc_def.inc.
    Move and rename info for chapter-old from doc-old to doc-new.
  • Clean + compile doc-new.
    Analyze error messages and correct errors.
    E.g. get missing substitutions/references/images/data from doc-old.
  • Clean + compile doc-old.
    Analyze error messages and correct errors.

2.7.3. How to move a section from one chapter file to another chapter file

  • Remove section-old section from chapter-old.
    Insert as section-new in chapter-new.
  • Clean + compile doc-new.
    Analyze error messages and correct errors.
    E.g. get missing substitutions/references/images/data from doc-old.
  • Clean + compile doc-old.
    Analyze error messages and correct errors.

2.7.4. Traceability of section modifications

|:todo:| incorrect, needs to be updated

Case-by-case analysis:

  1. Move sections before chapter documents:

    • Section section-old moved from chapter-old to chapter-new in doc-old
    • chapter-new moved from doc-old to chapter-new in doc-new
    • chapter-new moved to chapter-new-new in doc-new

    Consequences:

    • doc-old no longer exists. It must be looked up in the document processing logs.
    • doc-new no longer exists. It must be looked up in the document processing logs.
    • The version history of the section modification resides in the old repositories (doc-old, :doc-new).
  2. Move chapter documents before sections:

    • doc-old moved to doc-old-new
    • doc-new moved to doc-new-new
    • Section section moved from doc-old-new to doc-new-new

    Consequences:

    • The version history of the section modification resides in the new repositories (doc-old-new, :doc-new-new), which is better.

2.8. ReST section overlines

manual (book) class:

File Book title Chapter Section Subsection Paragraph Subparagraph
README.txt ### === --- ~~~ ...  
README-chapter-topic.txt   ### === --- ~~~ ...

howto (article) class:

File Article title Section Subsection Paragraph Subparagraph
README.txt ### === --- ~~~ ...
README-chapter-topic.txt ### === --- ~~~ ...