.. -*- coding: utf-8 -*- .. role:: sref(numref) .. role:: xref(numref) .. Copyright (C) 2018, Wolfgang Scherer, .. .. This file is part of Documentation Standard. .. .. Permission is granted to copy, distribute and/or modify this document .. under the terms of the GNU Free Documentation License, Version 1.3 .. or any later version published by the Free Software Foundation; .. with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. .. A copy of the license is included in the section entitled "GNU .. Free Documentation License". .. inline comments (with du_comment_role) .. role:: rem(comment) .. role:: html(raw) :format: html .. role:: shx(code) :language: sh .. rst-class:: xnarrow xmedium large xhuge xultra .. _`sec:Sphinx Documentation Generator`: #################################################### :rem:`|||:sec:|||`\ Sphinx Documentation Generator #################################################### .. >>CODD See `the components of a doctoral dissertation and their order `_ .. >>CODD Dedication .. >>CODD Epigraph .. >>CODD Abstract .. compound:: The basic requirements for a documentation generator are as follows: - Must extract documentation from source code. (`Sphinx`_, `Doxygen`_). - Must include full source code with the documentation. (`Sphinx`_, `Doxygen`_). - | Should be extensible for integration of format converters. | `Sphinx`_ extensions are simple, as it is written in Python. | `Doxygen`_ extensions are virtually non-existent, since `Doxygen`_ is written in C++. See the `PlantUML integration with Doxygen `_ for an elaborate example. - Should be hackable. (`Sphinx`_). - Should come with source code. (`Sphinx`_, `Doxygen`_). Since `Sphinx`_ is easily extendable, because there is a `Doxygen`_ to `Sphinx`_ bridge, and it is ultimately hackable, `Sphinx`_ is the logical choice for overall documentation. .. \|:here:| .. >>CODD Introduction .. >>CODD Chapter ==================================================== :rem:`|||:sec:|||`\ ReStructuredText Tips and Issues ==================================================== ----------------------------------------------------------- :rem:`||:sec:||`\ Spaces at the beginning of formatted text ----------------------------------------------------------- There is a problem with blank spaces at the beginning of formatted text. It cannot be solved with no-break spaces (:kbd:`C-q 240 RET`). E.g., this:: | NO-BREAK SPACE: >`` ``< | NO-BREAK SPACE: >:literal:` `< renders like this with warnings: | NO-BREAK SPACE: >\ |fake-inline-literal-no-break-space|\ < | NO-BREAK SPACE: >\ |fake-role-literal-no-break-space|\ < .. |fake-inline-literal-no-break-space| unicode:: ``​ U+00A0 `` .. |fake-role-literal-no-break-space| unicode:: :literal:` U+00A0 ` Other methods also don't work, e.g., substitutions are not recognized within formatted text. It is, however, possible to use a `SPACE` (or `NO-BREAK SPACE`) enclosed in unicode characters `ZERO WIDTH SPACE`:: | ZERO WIDTH SPACE + SPACE + ZERO WIDTH SPACE: >``​ ​``< | ZERO WIDTH SPACE + NO-BREAK SPACE + ZERO WIDTH SPACE: >``​ ​``< which renders like this: | ZERO WIDTH SPACE + SPACE + ZERO WIDTH SPACE: >\ ``​ ​``\ < | ZERO WIDTH SPACE + NO-BREAK SPACE + ZERO WIDTH SPACE: >\ ``​ ​``\ < See also `how to document a single space character within a string in reST/Sphinx?`_: ------------------------------------------------------- :rem:`||:sec:||`\ Invisible substitutions (space/blank) ------------------------------------------------------- +---------------+--------+--------+---------------------------+ | Glyph | LaTeX? | Code | Unicode Name | +===============+========+========+===========================+ | >\ |SPC|\ < | √ | U+0020 | SPACE | +---------------+--------+--------+---------------------------+ | >\ |NBSP|\ < | √ | U+00A0 | NO-BREAK SPACE | +---------------+--------+--------+---------------------------+ | >\ |ZSPC|\ < | \- | U+200B | ZERO WIDTH SPACE | +---------------+--------+--------+---------------------------+ | >\ |ZNBSP|\ < | √ | U+FEFF | ZERO WIDTH NO-BREAK SPACE | +---------------+--------+--------+---------------------------+ These defintions can be used to add invisible breaks in the document structure:: .. |SPC| unicode:: U+0020 .. SPACE .. |NBSP| unicode:: U+00A0 .. NO-BREAK SPACE .. |RSPC| replace:: :rem:`x` :rem:`x` .. |ZSPC| unicode:: U+200B .. ZERO WIDTH SPACE .. |ZNBSP| unicode:: U+FEFF .. ZERO WIDTH NO-BREAK SPACE .. |RZSPC| replace:: \ :rem:`x` | > |SPC| < | > |NBSP| < | > |RSPC| < | > |ZSPC| < | > |ZNBSP| < | > |RZSPC| < Which renders as: | > |SPC| < | > |NBSP| < | > |RSPC| < | > |ZSPC| < | > |ZNBSP| < | > |RZSPC| < These definitions can also be used with backslash whitespace suppression:: | >\ |SPC|\ < | >\ |NBSP|\ < | >\ |RSPC|\ < | >\ |ZSPC|\ < | >\ |ZNBSP|\ < | >\ |RZSPC|\ < Which renders as: | >\ |SPC|\ < | >\ |NBSP|\ < | >\ |RSPC|\ < | >\ |ZSPC|\ < | >\ |ZNBSP|\ < | >\ |RZSPC|\ < The same effect can be achieved with the `:trim:` option of the `unicode` directive:: | >\ |GSPC|\ < | >\ |GZSPC|\ < .. |GSPC| unicode:: U+0020 .. GREEDY SPACE :trim: .. |GZSPC| unicode:: U+200B .. GREEDY ZERO WIDTH SPACE :trim: Which renders as: | >\ |GSPC|\ < | >\ |GZSPC|\ < .. |SPC| unicode:: U+0020 .. SPACE .. |NBSP| unicode:: U+00A0 .. NO-BREAK SPACE .. |RSPC| replace:: :rem:`x` :rem:`x` .. |ZSPC| unicode:: U+200B .. ZERO WIDTH SPACE .. |ZNBSP| unicode:: U+FEFF .. ZERO WIDTH NO-BREAK SPACE .. |RZSPC| replace:: \ :rem:`x` .. |GSPC| unicode:: U+0020 .. GREEDY SPACE :trim: .. |GZSPC| unicode:: U+200B .. GREEDY ZERO WIDTH SPACE :trim: .. _`how to document a single space character within a string in reST/Sphinx?`: https://stackoverflow.com/questions/31304522/how-to-document-a-single-space-character-within-a-string-in-rest-sphinx -------------------------------------------------- :rem:`||:sec:||`\ Representing space characters -------------------------------------------------- Besides textual descriptions like ``SPC`` and ``SPACE``, there are some Unicode characters: +-------+--------+--------+---------------------+ | Glyph | LaTeX? | Code | Unicode Name | +=======+========+========+=====================+ | **␣** | √ | U+2423 | OPEN BOX | +-------+--------+--------+---------------------+ | **␢** | √ | U+2422 | BLANK SYMBOL | +-------+--------+--------+---------------------+ | **␠** | \- | U+2420 | SYMBOL FOR SPACE | +-------+--------+--------+---------------------+ | ⍽ | \- | U+237D | SHOULDERED OPEN BOX | +-------+--------+--------+---------------------+ See question `What character can I use to represent the space bar?`_, info about `Unicode spaces`_, LaTeX: `Explicit space character?`_ .. _`What character can I use to represent the space bar?`: https://ux.stackexchange.com/questions/55220/what-character-can-i-use-to-represent-the-space-bar .. _`Unicode spaces`: http://jkorpela.fi/chars/spaces.html .. _`Explicit space character?`: https://tex.stackexchange.com/questions/50804/explicit-space-character -------------------------------------------------- :rem:`||:sec:||`\ LaTeX Unicode declarations -------------------------------------------------- Here are LaTeX preamble declarations for the above missing unicode characters:: \usepackage{pmboxdraw} \ifdefined\DeclareUnicodeCharacter %% ZERO WIDTH SPACE \DeclareUnicodeCharacter{200B}{} %% SYMBOL FOR SPACE \DeclareUnicodeCharacter{2420}{{\tiny\raisebox{1ex}[.5\ht\strutbox][0pt]{S}{P}}} %% SHOULDERED OPEN BOX \DeclareUnicodeCharacter{237D}{\textvisiblespace} \fi These declarations are already included in the standard `sphinx-doc` framework. ================================================== :rem:`|||:sec:|||`\ Slides ================================================== Slides extensions come as HTML themes, standalone targets and for docutils only. -------------------------------------------------- :rem:`||:sec:||`\ HTML theme -------------------------------------------------- - `sphinxjp.themes.revealjs`_ - `reveal.js `__ presentation style theme for Sphinx `Source on github `__ forked from `tell-k `_. Using `return42` fork, since on 2019-06-21 the pull request from 2019-05-01 spanning 2 years is still open. - Set up separate document directory, if applicable, e.g. :file:`doc-slides`. - The main document may be an index README or a normal chapter, e.g. :file:`README-slides.txt`. - In :file:`doc-slides/Makefile` set :make:var:`MAIN_DOC` to :file:`README-slides.txt`, and :make:var:`PRESENTATION` to 1: .. code-block:: make PRESENTATION = 1 MAIN_DOC = README-slides.txt - In :file:`doc-slides/conf.py` activate the `revealjs` HTML theme. .. note:: As of 2019-06-22, `sphinxjp.themes.revealjs`_ is integrated into :program:`inst.sh` and snippets. It only needs to be activated in :file:`Makefile` and :file:`conf.py`. .. code-block:: sh pip install https://github.com/return42/sphinxjp.themes.revealjs/archive/master.zip #pip install sphinxjp.themes.revealjs in :file:`conf.py` .. code-block:: py extensions = ['sphinxjp.themes.revealjs'] html_theme = 'revealjs' html_use_index = False html_theme_options = { 'width': 1920, 'height': 1080, "margin": 0, } render with .. code-block:: sh make html .. _`sphinxjp.themes.revealjs`: http://pythonhosted.org/sphinxjp.themes.revealjs - `sphinxjp.themes.impressjs`_ provides `impressjs` directive for `impress.js` presentation control, provides impressjs presentation theme for rendering HTML documents. `Source on github `__ .. code-block:: sh pip install sphinxjp.themes.impressjs in :file:`conf.py` .. code-block:: py extensions = ['sphinxjp.themes.impressjs'] html_theme = 'sphinxjp.themes.impressjs' html_use_index = False render with .. code-block:: sh make html .. _`sphinxjp.themes.impressjs`: https://pythonhosted.org/sphinxjp.themes.impressjs/#/installation - `htmlslide`_ `Source on bitbucket `__ .. code-block:: sh pip install sphinxjp.themes.htmlslide in :file:`conf.py` .. code-block:: py extensions = ['sphinxjp.themecore'] html_theme = 'htmlslide' pygments_style = 'monokai' Edit source, each section is a slide. Render with .. code-block:: sh make html .. _`htmlslide`: https://pythonhosted.org/sphinxjp.themes.htmlslide/ -------------------------------------------------- :rem:`||:sec:||`\ Standalone target -------------------------------------------------- - `Hieroglyph`_ `Source on github `__ .. code-block:: sh pip install hieroglyph in :file:`conf.py` .. code-block:: py extensions = ['hieroglyph'] render with .. code-block:: sh make slides .. _`Hieroglyph`: http://docs.hieroglyph.io/en/latest/index.html -------------------------------------------------- :rem:`||:sec:||`\ Docutils only -------------------------------------------------- - `Easy Slide Shows With reST & S5`_ .. _`Easy Slide Shows With reST & S5`: https://docutils.readthedocs.io/en/sphinx-docs/user/slide-shows.html ================================= :rem:`|||:sec:|||`\ Sphinx Themes ================================= :: apt-get install python-sphinx-rtd-theme easy_integration git://github.com/snide/sphinx_rtd_theme apt-get install python-alabaster easy_install git://github.com/bitprophet/alabaster apt-get install python-sphinx-bootstrap-theme easy_install git://github.com/ryan-roemer/sphinx-bootstrap-theme apt-get install python-guzzle-sphinx-theme easy_install git://github.com/guzzle/guzzle_sphinx_theme apt-get install python-openstackdocstheme apt-get install python-cloud-sptheme ================================================== :rem:`|||:sec:|||`\ Graphviz Dot ================================================== The built-in `Sphinx`_ extension `sphinx.ext.graphviz`_ allows graphviz dot(1) graphs to be specified with the :rst:dir:`graphviz`, :rst:dir:`graph` and :rst:dir:`digraph` directives in the `reStructuredText`_ source: .. code-block:: c .. graphviz:: digraph "foo" { rankdir=LR; "baz" [shape=box]; "bar" -> "baz" -> "quux"; "quux" -> "baz" -> "bar"; } This is rendered as: .. graphviz:: digraph "foo" { rankdir=LR; "baz" [shape=box]; "bar" -> "baz" -> "quux"; "quux" -> "baz" -> "bar"; } The emacs shortcut :kbd:`Ctrl-c u u d` calls the command :command:`x-graphviz-dot-preview-current-directive`, which displays a preview of the current :rst:dir:`graphviz` directive. -------------------------------------------------- :rem:`||:sec:||`\ Graphviz dot(1) Information -------------------------------------------------- Besides the `man page for dot(1)`_, and the `Graphviz web site`_, the `GraphViz Reference`_ is a good resource for - `Node, Edge and Graph Attributes`_ - supported HTML elements in `HTML-Like Labels`_ of `nodes` with shape `plaintext`. snippets(1) also provides for a basic graph template with a choice of interesting options and examples:: snn -m dot .. _`man page for dot(1)`: https://www.mankier.com/1/dot .. _`Graphviz web site`: https://www.graphviz.org/ .. _`GraphViz Reference`: https://www.graphviz.org/doc/info/ .. _`HTML-Like Labels`: https://www.graphviz.org/doc/info/shapes.html#html .. _`Node, Edge and Graph Attributes`: https://www.graphviz.org/doc/info/attrs.html .. _`sphinx.ext.graphviz`: http://www.sphinx-doc.org/en/master/ext/graphviz.html .. \|:here:| ==================================== :rem:`|||:sec:|||`\ Sphinx Mercurial ==================================== See `sphinxcontrib-mercurial`_. Usage:: .. hg_version:: .. hg_changelog:: :repo_root_path: .. :max_commits: 5 :branch: default :path: some/file_or_dir .. The HG version: .. hg_version:: The HG changelog: .. hg_changelog:: :max_commits: 5 The updated package :command:`python-sphinxcontrib.mercurial` is in the local package repository and can be installed with:: apt-get install python-sphinxcontrib.mercurial Manual installation from original sources:: wget -q https://pypi.python.org/packages/88/3f/dccabe4be8c71df0c503c0754c323a81105d35c4ba6625788eb03a2ffc04/sphinxcontrib-mercurial-0.2.tar.gz tar -zxf sphinxcontrib-mercurial-0.2.tar.gz ( cd sphinxcontrib-mercurial-0.2/sphinxcontrib/mercurial || exit 1 patch -p0 <<'EOF' --- hg_changelog.orig.py 2012-10-27 11:14:35.000000000 +0200 +++ hg_changelog.py 2018-04-09 11:55:41.665255313 +0200 @@ -14,12 +14,14 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . +import os +import sys + from docutils import nodes from docutils.parsers.rst import directives from sphinx.util.compat import Directive -from mercurial import ui, hg, util - +from mercurial import ui, hg, util, cmdutil class HgChangeLog(Directive): has_content = True @@ -37,6 +39,11 @@ repo_root_path = "." if 'repo_root_path' in self.options: repo_root_path = self.options['repo_root_path'] + else: + repo_root_path = cmdutil.findrepo(os.path.abspath('.')) + if not repo_root_path: + sys.stderr.write('error: hg_changelog: no Repository found\n') + return [] repo = hg.repository(ui.ui(), repo_root_path) l = nodes.bullet_list() @@ -91,4 +98,3 @@ if f.startswith(path): return True return False - EOF ) cp -pr sphinxcontrib-mercurial-0.2/sphinxcontrib/mercurial /usr/lib/python2.7/dist-packages/sphinxcontrib/ .. _sphinxcontrib-mercurial: https://pypi.python.org/pypi/sphinxcontrib-mercurial/ ================================================================= :rem:`|||:sec:|||`\ ReStructuredText and Sphinx bridge to Doxygen ================================================================= `Doxygen`_ can produce XML output. This is used by the `Breathe`_ `Sphinx`_ extension to incorporate Doxygen output into `Sphinx`_ via directives: .. code-block:: rest .. doxygenclass:: Nutshell :project: nutshell :members: .. _`Breathe`: https://github.com/michaeljones/breathe .. _`michaeljones/breathe: ReStructuredText and Sphinx bridge to Doxygen`: https://github.com/michaeljones/breathe .. >>CODD Conclusion .. >>CODD Appendix A .. \|:here:| .. >>CODD Notes .. ================================================== .. :rem:`|||:sec:|||`\ Footnotes .. ================================================== :html:`
` .. \[#] .. include:: doc_defs.inc .. include:: doc_defs_combined.inc .. include:: abbrev_defs.inc .. .. \||<-snap->|| doc_standalone .. include:: doc/doc_defs_secret.inc .. \||<-snap->|| doc_standalone .. \||<-snap->|| not_doc_standalone .. include:: doc_defs_secret.inc .. \||<-snap->|| not_doc_standalone .. _`Wolfgang Scherer`: wolfgang.scherer@gmx.de