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.
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.,
at least one command or an equivalent must be excuted. There is no exception to this requirement.
The command
sda chapter new 'Chapter title'
is roughly equivalent to
snn --mode rst --key title --value 'Chapter title' README-chapter-title.txt
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.
sda readme README.txt # => README.html
sda readme --format pdf README.txt # => README.pdf
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' )"
|: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).
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).
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.
Document administration is performed with sda, a shortcut link to sphinx-doc-admin.sh.
Add automodule documentation files for python modules to the
doc
directory.
sda automodule MODULE-OR-FILE ...
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
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`
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.
Move README-chapter-old.txt
to README-chapter-new.txt
.
Move README-chapter-old.txt
from doc-old to README-chapter-new.txt
in doc-new.
doc/doc_def_standalone.inc
in doc/doc_def.inc
.
|:todo:| incorrect, needs to be updated
Case-by-case analysis:
Move sections before chapter documents:
Consequences:
Move chapter documents before sections:
Consequences:
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 | ### |
=== |
--- |
~~~ |
... |