Documentation Standard¶

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

• Documentation is maintained in the source code and in ASCII files named README.txt or README-topic.txt, since binary documentation (Word, Visio) that requires a graphical user interface for viewing/editing is extremely counterprodcutive (See section 8, Relevance of Documentation).
• reStructuredText is used as markup language. It also happens to be the official markup language for the Python programming language.
• Sphinx extends the roles and directives of reStructuredText. It converts documents and Python doc strings to various formats such as HTML, PDF and EPUB. (See section 14, Sphinx Documentation Generator).
• UML diagrams are used to visualize programm design and script algorithms. (See section 12, Unified Modeling Language).
• PlantUML is the program of choice for converting textual diagram descriptions into SVG, PNG or PDF images. (See local copy of PlantUML Language Reference Guide).
• |:todo:| Integrate Lightbox2 to display full version of images.

| README-redistribution-of-info-items.txt                  | * /home/sw/project/administration     | #mv# /home/da/project/documentation |

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

SDL

see Specification and Description Language

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)

Specification and Description Language

A standardized language, described by Wikipedia[WPSDL]:

As of 2016 its current areas of application include process control and real-time applications in general. Due to its nature it can be used to represent simulation systems without ambiguity and with a graphical notation.

References