Documentation Standard

this is not a pipe The famous pipe. How people reproached me for it! And yet, could you stuff my pipe? No, it’s just a representation, is it not? So if I had written on my picture ‘This is a pipe’, I’d have been lying!

—René Magritte[TORC]

No software survives contact with the user.

—not Helmuth von Moltke the Elder

There is a PDF version of this document available.

Quickstart

Single shot standalone document:

sda chapter new 'Doc Title'        # => README-doc-title.txt

sda readme README-doc-title.txt              # => README-doc-title.html
sda readme -f p README-doc-title.txt         # => README-doc-title.pdf
sda readme --format pdf README-doc-title.txt # => README-doc-title.pdf

Book w/chapter documents:

sda init  "Project Title"          # => README.txt + doc/
sda chapter add "Title"            # => add chapter README-title.txt
sda automodule MODULE              # => module documentation from template

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' )"

sda make clean                     # remove generated files => rm -rf doc/_build/
                                   # (necesary, when e.g., new chapters are added)

Update sphinx-doc framework for book documents (requires manual resolution!):

sda update                         # => book/README.txt + book/doc (re-created for update)

Find sphinx-doc directories:

sda locate --home
sda locate --sed SCRIPT

sda locate --grep [OPTIONS] [PATTERN]

Abstract

Contents

Abbreviations

ABBR
see Abbreviation
EASE
Eclipse Advanced Scripting Environment
HTML
see HyperText Markup Language
HTTP
Hypertext Transfer Protocol
IDE
Integrated Development Environment
JPEG
see Joint Photographic Experts Group
PDF
Portable Document Format
PNG
see Portable Network Graphics
REST
Representational State Transfer
RPC
Remote Procedure Call
SGML
Standard Generalized Markup Language
SVG
Scalable Vector Graphics
XML
see Extensible Markup Language

Glossary

Abbreviation

As Wikipedia describes it[WPABBR]:

An abbreviation (from Latin brevis, meaning short) is a shortened form of a word or phrase. It consists of a group of letters taken from the word or phrase. For example, the word abbreviation can itself be represented by the abbreviation abbr., abbrv., or abbrev.
Extensible Markup Language
An SGML application like HTML.
HyperText Markup Language
An SGML application.
Joint Photographic Experts Group
Norm ISO/IEC 10918-1, image file format
Portable Network Graphics
An image file format (.PNG)

References

[WPABBR]Wikipedia contributors. (2019, May 9). Abbreviation. In Wikipedia, The FreeEncyclopedia. Retrieved 15:58, May 21, 2019, from <https://en.wikipedia.org/w/index.php?title=Abbreviation&oldid=896285984>
[TORC]Torczyner, Harry. Magritte: Ideas and Images. p. 71. ISBN 978-0-8109-1300-4.