The full HTML document is available in the Sphinx HTML build directory .. ||<-snap->|| not_doc_md
| Author: | Wolfgang Scherer |
|---|
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.
There is a PDF version of this document available.
Quickstart
Abstract
- Documentation is maintained in the source code and in ASCII files named
README.txtorREADME-topic.txt, since binary documentation (Word, Visio) that requires a graphical user interface for viewing/editing is extremely counterprodcutive (See |chapter-relevance|).- `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 |chapter-sphinx|).
- `UML diagrams`_ are used to visualize programm design and script algorithms. (See |chapter-uml|).
- `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
The documentation framework described in |chapter-sphinx-doc|, supports single file articles and books with chapters and fully configurable build environment. With a separate doc directory, a subset of chapters can be built as a book part.
The documentation is processed with the `Sphinx`_ document generator to produce various output formats (see |chapter-sphinx|).
The theory behind Sphinx Doc is discussed in |chapter-relevance|.
The reasons for advanced concepts like document snippets, which expand the traditional knowledge collection beyond simple cross referencing (hyperlinks), are discussed in |chapter-knowledge|.
.. ||<-snap->|| not_doc_md
References
Copyright
Copyright (C) 2018, 2019, 2021 Wolfgang Scherer, <Wolfgang.Scherer at gmx.de>. See the document source for conditions of use under the GNU Free Documentation License.