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 requirement.

figure 2.1 Documentation workflow¶

2.2. Initialize documentation¶

2.2.1. New article¶

The command

sda chapter new 'Chapter title'

is roughly equivalent to

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¶

|:todo:| add to glossary

The book directory must not have any uncommitted changes.
The book directory must be synchronized with master repository.
The book at the book directory should build without warnings.

If there are warnings, record them to be able to distinguish between old warnings and new warnings.
```
sda make clean
sda make html
sda make pdf
```
Update template framework (snippets) at the book directory
```
sda update
```
This creates a new sub-directory BOOK-DIR-update 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 in BOOK-DIR-update, that are not present in BOOK-DIR updated, are moved to the corresponding location. Files that are identical (ignoring copyright lines) are deleted. (see figure 2.3).

figure 2.3 SphinxDoc - compare updated files with original tree¶

Files in BOOK-DIR-update that differ from files in BOOK-DIR must be merged manually with M-x ediff-directories or kdiff3(1).

(let* ((project (file-name-base (directory-file-name default-directory)))
       (update (concat default-directory project "-update")))
  (ediff-directories update default-directory ""))

Run a fresh build to detect any errors.
Commit changes using the phrase template framework update (don’t forget adding new files).
Push commits to master repository.
Publish repository.
Remove update directory.

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 12, 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 14, 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:

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).
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	`###`	`===`	`---`	`~~~`	`...`