Document snippets solve the problem of describing mutliple
processes which consist of partial common subsets of tasks and
additional unique tasks for each process. Document snippets are
defined by enclosing sections in |<-snip->|
tags. The document
snippets are then inserted at places marked with a |<-snap->|
tag. The sphinx_doc_snip.py tool also provides
replacement facilities for creating specific versions of generic
documents.
A document snippet is enclosed in |<-snip->|
tags, which
must start in column 0:
>|<-snip->|
>DOCUMENT SNIPPET BODY
>|<-snip->|
The tags can also be commented as .. \|<-snip->|
:
>.. \|<-snip->|
>DOCUMENT SNIPPET BODY
>.. \|<-snip->|
An item prefix is a non-empty string at the beginning of a line, consisting of
-
, plus +
, asterisks *
, hash dot #.
, integer dot 1.
, or space ␣
␣
.An item prefix matches the regular expression (␣*([-+*␣]|(?:[#]|[0-9]+)[.])␣+)
).
When a |<-snip->|
tag is preceded by an item prefix the end marker is recognized at the same indentation:
> - |<-snip->| item text ...
> item text ...
> .. \|<-snip->| snippet title
>- |<-snip->| some item
>
> item body filled with stuff.
> item body filled with stuff.
>
> .. \|<-snip->| item 1
>
> * |<-snip->| some indented item
>
> indented item body filled with stuff.
> indented item body filled with stuff.
>
> .. \|<-snip->| item 2
some item
item body filled with stuff. item body filled with stuff.
some indented item
indented item body filled with stuff. indented item body filled with stuff.
The possible names of the document snippet are derived from
the title given after the starting or ending .. \|<-snip->|
marker:
.. \|<-snip->| Most Preferred Snippet Title
If the starting |<-snip->|
tag has an item prefix, the title is
only recognized for the end marker.
the first section title:
.. \|<-snip->|
--------------------------------------------------
:rem:`||:sec:||`\ Snippet Section Title
--------------------------------------------------
.. \|<-snip->|
the first label in the snippet body:
.. \|<-snip->|
.. _`Snippet Section Title Ref`:
.. \|<-snip->|
The names are used in that order as title candidates for document snippet references.
The first argument of the starting .. \|<-snip->|
marker is
evaluated as a string of flags consisting of:
-
Here is a document snippet definition named Snippet Section Title
Ref
, with a section title of Snippet Section Title
and an extra
title Snippet Section Extra Name
:
.. \|<-snip->| - Snippet Section Extra Name
.. _`Snippet Section Title Ref`:
--------------------------------------------------
:rem:`||:sec:||`\ Snippet Section Title
--------------------------------------------------
section body ...
.. \|<-snip->|
An unlabeled document snippet with section header:
.. \|<-snip->|
--------------------------------------------------
:rem:`||:sec:||`\ Unlabeled Snippet Title
--------------------------------------------------
section body ...
.. \|<-snip->|
A named document snippet without label or section header:
.. \|<-snip->| named snippet
.. \|<-snip->|
The document snippet tags |<-snip->|
and |<-snap->|
are
defined as substitutions, which are effectively blank:
.. |<-snip->| replace:: \ :rem:`x`
.. |<-snap->| replace:: \ :rem:`x`
A document snippet reference is recognized, when a line starts with a
|<-snap->|
tag:
>|<-snap->| :ref:`Snippet Tag Substitutions Label`
In this case, the entire snippet definition including the section header (and section label if appropriate) are substituted for the reference line.
If a |<-snap->|
tag is preceded by an item prefix, e.g.:
>- |<-snap->| `Snippet Tag Substitutions`_
>+ |<-snap->| `Snippet Tag Substitutions`_
>* |<-snap->| :ref:`Snippet Tag Substitutions Label`
>␣ |<-snap->| `Snippet Tag Substitutions`_
>1. |<-snap->| :ref:`Snippet Tag Substitutions Label`
>#. |<-snap->| :ref:`Snippet Tag Substitutions Label`
the snippet is inserted properly indented as item without label and section header:
- snippet body
snippet body
A document snippet reference is also recognized as comment:
>.. \|<-snap->| named snippet
>.. - |<-snap->| named snippet
>.. * |<-snap->| named snippet
Here are some live examples from the item snippets defined above. They are actually expanded in the resolved version of this document.
item 1
item 2
The tags |<-sn0p->|
, |<-sn1p->|
, … |<-sn9p->|
are
equivalent to the |<-snap->|
tag with the following additional
features:
Code | Feature |
---|---|
0 | remove item prefix, process as section |
1 | Bold Title |
2 | Bold Title, replace item bullet |
3 | Definition List (title = term) |
4 | Definition List (title = term), replace item bullet |
5 | Field List (title = field) |
6 | Field List (title = field), replace item bullet |
7 | undefiniert |
8 | undefiniert |
9 | undefiniert |
For a snippet reference with |<-sn1p->|
tag:
>* |<-sn1p->| :ref:`Snippet Tag Substitutions Label`
the snippet title is added as bold header:
* **Snippet Tag Defintions**
snippet body
snippet body
With a |<-sn2p->|
tag:
>* |<-sn2p->| :ref:`Snippet Tag Substitutions Label`
the bullet indentation is removed and the snippet title is added as bold header:
**Snippet Tag Defintions**
snippet body
snippet body
Here are some live examples from the item snippets defined above. They are actually expanded in the resolved version of this document.
fixed item
item 2
expanded with bold title
item 2
expanded with bold title, item removed
Some definitions:
item 2
item 1
Some fields:
item 2
item 1
Itemized list expanding into various things:
item 2
expanding as definition, extended with some stuff
item 2
expanding as field, extended with some stuff
The tags |<-sn#p->|
, |<-sn=p->|
, |<-sn-p->|
,
|<-sn~p->|
, |<-sn.p->|
, |<-sn+p->|
, are equivalent to the
|<-snap->|
tag, however they explicitely change the section header
over-/underline. If the referenced snippet does not have a section
header, it is generated from the title.
In the resolved document, the following section is moved from above to here:
The following item, tagged with |<-snap->|
is either rendered as a
ReST reference in the source document or the actual document snippet
is inserted without a section title during the document snippet
resolution pass:
The following item, tagged with |<-sn1p->|
is either rendered as
a ReST reference in the source document or the actual document
snippet is inserted with a section title during the document
snippet resolution pass:
Here comes a demoted version of the section …
See section Replacements in sphinx_doc_snip.py for a details.
In the resolved version, both sides will read laptop-mb:
@hostname@ => laptop-mb
sphinx_doc_snip.py - process sphinx-doc document snippets.
usage: | sphinx_doc_snip.py [OPTIONS] file-to-process … |
or | import sphinx_doc_snip |
–force overwrite existing files. –no-defaults do not read default configuration files. -c, –config CFG add CFG to list of configuration files. -i, –include INC add INC as document to parse for snippets only. The document is not resolved. -r, –replace REPL add replacement WHAT=WITH. @WHAT@ is replaced by string WITH after resolving snippets. -f, –format FMT format for output documents. Default: {dir}/{base}-x{ext}. Placeholders: path, dir, file, base, ext, sbase (secondary base of base), sext. If format is -, standard output is used. –html convert to HTML with sphinx-readme.sh(1) convert to PDF with sphinx-readme.sh(1) -q, –quiet suppress warnings -v, –verbose verbose test output -d, –debug[=NUM] show debug information -h, –help display this help message –template list show available templates. –eide[=COMM] Emacs IDE template list (implies –template list). –template[=NAME] extract named template to standard output. Default NAME is -
.–extract[=DIR] extract adhoc files to directory DIR (default: .
)–explode[=DIR] explode script with adhoc in directory DIR (default __adhoc__
)–setup[=install] explode script into temporary directory and call python setup.py install –implode implode script with adhoc -t, –test run doc tests
sphinx_doc_snip.py parses a set of documents for document snippet defintions and resolves document snippet references accordingly. The specification is in section 17, Document Snippets.
The configuration files
are read in that order.
Example:
FORCE=no
FORMAT='{sbase}{sext}'
INCLUDE='
README.txt
README-stations.txt
'
REPLACE='
user=Max Benutzer
user_short=mb
'
The replacement facility allows to specify arbitrary replacement text
for placeholders enclosed in @
. With the following replacement
options:
replacement option | placeholder | replacement |
---|---|---|
–replace ‘user=Max Benutzer’ | @user@ | Max Benutzer |
–replace ‘user_short=mb’ | @user_short@ | mb |
–replace ‘hostname_pfx=laptop-‘ | @hostname_pfx@ | laptop- |
–replace ‘hostname=@hostname_pfx@@user_short@’ | @hostname@ | @hostname_pfx@@user_short@ |
the placeholder @hostname@ is replaced recursively accordingly:
@hostname@ => laptop-mb
>>> for ex in __all__: printf(sformat('from {0} import {1}', __name__, ex))
from sphinx_doc_snip import Documentation
from sphinx_doc_snip import Document
from sphinx_doc_snip import Snippet
from sphinx_doc_snip import Section
>>> if '__all_internal__' in globals():
... for ex in __all_internal__:
... printf(sformat('from {0} import {1}', __name__, ex))
sphinx_doc_snip.
Documentation
(*args, **kwargs)[source]¶>>> _docs = Documentation()
>>> _docs.register(Document((1, 'doc_snippet_test.rst', DOC_SNIPPET_TEST)))
True
>>> _docs.dump_snippets(file=sys.stdout)
..
.. --------------------------------------------------
.. \|<-snip->| Labeled Section | Labeled Section Label
--------------------------------------------------
:rem:`||:sec:||`\ Labeled Section
--------------------------------------------------
Section body filled with labeled stuff.
Section body filled with labeled stuff.
Section body filled with labeled stuff.
<BLANKLINE>
field: value
field: value
..
.. --------------------------------------------------
.. \|<-snip->| - Unlabeled Section
--------------------------------------------------
:rem:`||:sec:||`\ Unlabeled Section
--------------------------------------------------
Section body filled with unlabeled stuff.
Section body filled with unlabeled stuff.
Section body filled with unlabeled stuff.
..
.. --------------------------------------------------
.. \|<-snip->| named paragraph
Section body filled with named stuff.
Section body filled with named stuff.
Section body filled with named stuff.
..
.. --------------------------------------------------
.. \|<-snip->| item 1
some item
<BLANKLINE>
item body filled with stuff.
item body filled with stuff.
..
.. --------------------------------------------------
.. \|<-snip->| item 2
some indented item
<BLANKLINE>
indented item body filled with stuff.
indented item body filled with stuff.
sphinx_doc_snip.
Document
(*args, **kwargs)[source]¶Initialize document, parse text or load from file handle/filename:
_doc = Document()
_doc.parse(TEXT)
_doc.load(file_handle)
_doc.load(filename)
Initialize document from filename (automatically loads file):
_doc = Document((1, 'filename'))
Initialize document from filename and text. Text is parsed and file is not loaded:
>>> _doc = Document((1, 'filename', DOC_SNIPPET_TEST))
>>> printf(_doc) #doctest: +ELLIPSIS
{
"filename": "filename",
"text": ".. \\|<-snip->|\n.. _Labeled Section Label:... |<-sn4p->| item 2\n |<-sn6p->| item 2",
"partition": {
"start_rx": {...},
"end_rx": {...},
"this": [],
"that": [],
"sections": [
...
]
},
"body": {
"start_rx": null,
"end_rx": null,
"this": [],
"that": [],
"sections": [
{
"start": ".. \\|<-snip->|",
"body": [
".. _Labeled Section Label:",
"",
"--------------------------------------------------",
":rem:`||:sec:||`\\ Labeled Section",
"--------------------------------------------------",
"",
"Section body filled with labeled stuff.",
"Section body filled with labeled stuff.",
"Section body filled with labeled stuff.",
"",
"field: value",
"field: value"
],
"end": ".. \\|<-snip->|",
"fsep": ": ",
"is_snippet": true,
"title": null,
"label": null,
"header": null,
"drop": null,
"titles": [
"Labeled Section",
"Labeled Section Label"
],
"pfx": "",
"label_done": null
},
{
"start": null,
"body": [
"",
"field: value",
"field: value",
""
],
"end": null,
"fsep": ": ",
"is_snippet": null
},
{
"start": null,
"body": [
""
],
"end": null,
"fsep": ": ",
"is_snippet": null
},
{
"start": ".. \\|<-snip->| named paragraph",
"body": [
"",
"Section body filled with named stuff.",
"Section body filled with named stuff.",
"Section body filled with named stuff.",
""
],
"end": ".. \\|<-snip->|",
"fsep": ": ",
"is_snippet": true,
"title": null,
"label": null,
"header": null,
"drop": null,
"titles": [
"named paragraph"
],
"pfx": "",
"label_done": null
},
{
"start": null,
"body": [
""
],
"end": null,
"fsep": ": ",
"is_snippet": null
},
{
"start": null,
"body": [
"- |<-snip->| some item",
"",
" item body filled with stuff.",
" item body filled with stuff."
],
"end": " .. \\|<-snip->| item 1",
"fsep": ": ",
"is_snippet": "-",
"title": null,
"label": null,
"header": null,
"drop": null,
"titles": [
"item 1"
],
"pfx": "- ",
"label_done": null
},
{
"start": null,
"body": [
""
],
"end": null,
"fsep": ": ",
"is_snippet": null
},
{
"start": null,
"body": [
" * |<-snip->| some indented item",
"",
" indented item body filled with stuff.",
" indented item body filled with stuff."
],
"end": " .. \\|<-snip->| item 2",
"fsep": ": ",
"is_snippet": "*",
"title": null,
"label": null,
"header": null,
"drop": null,
"titles": [
"item 2"
],
"pfx": " * ",
"label_done": null
},
{
"start": null,
"body": [
"",
".. |<-snap->| named paragraph",
"",
"- |<-snap->| see :ref:`Labeled Section Label`",
"- |<-sn1p->| see `Unlabeled Section`_",
"",
" #. |<-snap->| item 2",
" #. |<-snap->| item 1",
"",
" |<-sn1p->| item 2",
"",
" |<-sn3p->| item 2",
" |<-sn3p->| item 1",
"",
" |<-sn5p->| item 2",
" |<-sn5p->| item 1",
"",
" |<-sn4p->| item 2",
" |<-sn6p->| item 2"
],
"end": null,
"fsep": ": ",
"is_snippet": null
}
]
},
"snippets": {
"start_rx": null,
"end_rx": null,
"this": [],
"that": [],
"sections": [
{
"start": null,
"body": [
"Section body filled with labeled stuff.",
"Section body filled with labeled stuff.",
"Section body filled with labeled stuff.",
"",
"field: value",
"field: value"
],
"end": null,
"fsep": ": ",
"is_snippet": true,
"title": "Labeled Section",
"label": null,
"header": [
"--------------------------------------------------",
":rem:`||:sec:||`\\ Labeled Section",
"--------------------------------------------------"
],
"drop": null,
"titles": [
"Labeled Section",
"Labeled Section Label"
],
"pfx": "",
"label_done": null
},
{
"start": null,
"body": [
"Section body filled with unlabeled stuff.",
"Section body filled with unlabeled stuff.",
"Section body filled with unlabeled stuff."
],
"end": null,
"fsep": ": ",
"is_snippet": true,
"title": "Unlabeled Section",
"label": null,
"header": [
"--------------------------------------------------",
":rem:`||:sec:||`\\ Unlabeled Section",
"--------------------------------------------------"
],
"drop": true,
"titles": [
"Unlabeled Section"
],
"pfx": "",
"label_done": null
},
{
"start": null,
"body": [
"Section body filled with named stuff.",
"Section body filled with named stuff.",
"Section body filled with named stuff."
],
"end": null,
"fsep": ": ",
"is_snippet": true,
"title": "named paragraph",
"label": null,
"header": null,
"drop": null,
"titles": [
"named paragraph"
],
"pfx": "",
"label_done": null
},
{
"start": null,
"body": [
"some item",
"",
"item body filled with stuff.",
"item body filled with stuff."
],
"end": null,
"fsep": ": ",
"is_snippet": "-",
"title": "item 1",
"label": null,
"header": null,
"drop": null,
"titles": [
"item 1"
],
"pfx": "- ",
"label_done": null
},
{
"start": null,
"body": [
"some indented item",
"",
"indented item body filled with stuff.",
"indented item body filled with stuff."
],
"end": null,
"fsep": ": ",
"is_snippet": "*",
"title": "item 2",
"label": null,
"header": null,
"drop": null,
"titles": [
"item 2"
],
"pfx": " * ",
"label_done": null
}
]
},
"resolved": null
}
>>> _doc.dump_snippets(file=sys.stdout)
..
.. --------------------------------------------------
.. \|<-snip->| Labeled Section | Labeled Section Label
--------------------------------------------------
:rem:`||:sec:||`\ Labeled Section
--------------------------------------------------
Section body filled with labeled stuff.
Section body filled with labeled stuff.
Section body filled with labeled stuff.
<BLANKLINE>
field: value
field: value
..
.. --------------------------------------------------
.. \|<-snip->| - Unlabeled Section
--------------------------------------------------
:rem:`||:sec:||`\ Unlabeled Section
--------------------------------------------------
Section body filled with unlabeled stuff.
Section body filled with unlabeled stuff.
Section body filled with unlabeled stuff.
..
.. --------------------------------------------------
.. \|<-snip->| named paragraph
Section body filled with named stuff.
Section body filled with named stuff.
Section body filled with named stuff.
..
.. --------------------------------------------------
.. \|<-snip->| item 1
some item
<BLANKLINE>
item body filled with stuff.
item body filled with stuff.
..
.. --------------------------------------------------
.. \|<-snip->| item 2
some indented item
<BLANKLINE>
indented item body filled with stuff.
indented item body filled with stuff.
>>> printf(str(_doc.partition.sections) == DOC_SNIPPET_TEST)
True
>>> printf(str(_doc.body.sections) == DOC_SNIPPET_TEST)
False
>>> _resolved = _doc.resolve()
>>> printf(str(_resolved.sections))
.. \|<-snip->|
.. _Labeled Section Label:
<BLANKLINE>
--------------------------------------------------
:rem:`||:sec:||`\ Labeled Section
--------------------------------------------------
<BLANKLINE>
Section body filled with labeled stuff.
Section body filled with labeled stuff.
Section body filled with labeled stuff.
<BLANKLINE>
field: value
field: value
.. \|<-snip->|
<BLANKLINE>
field: value
field: value
<BLANKLINE>
<BLANKLINE>
.. \|<-snip->| named paragraph
<BLANKLINE>
Section body filled with named stuff.
Section body filled with named stuff.
Section body filled with named stuff.
<BLANKLINE>
.. \|<-snip->|
<BLANKLINE>
- |<-snip->| some item
<BLANKLINE>
item body filled with stuff.
item body filled with stuff.
.. \|<-snip->| item 1
<BLANKLINE>
* |<-snip->| some indented item
<BLANKLINE>
indented item body filled with stuff.
indented item body filled with stuff.
.. \|<-snip->| item 2
<BLANKLINE>
<BLANKLINE>
.. Source: .. |<-snap->| named paragraph
<BLANKLINE>
Section body filled with named stuff.
Section body filled with named stuff.
Section body filled with named stuff.
<BLANKLINE>
<BLANKLINE>
- Section body filled with labeled stuff.
Section body filled with labeled stuff.
Section body filled with labeled stuff.
<BLANKLINE>
field: value
field: value
<BLANKLINE>
.. Source: - |<-snap->| see :ref:`Labeled Section Label`
<BLANKLINE>
- **Unlabeled Section**
<BLANKLINE>
Section body filled with unlabeled stuff.
Section body filled with unlabeled stuff.
Section body filled with unlabeled stuff.
<BLANKLINE>
.. Source: - |<-sn1p->| see `Unlabeled Section`_
<BLANKLINE>
<BLANKLINE>
#. some indented item
<BLANKLINE>
indented item body filled with stuff.
indented item body filled with stuff.
<BLANKLINE>
.. Source: #. |<-snap->| item 2
<BLANKLINE>
#. some item
<BLANKLINE>
item body filled with stuff.
item body filled with stuff.
<BLANKLINE>
.. Source: #. |<-snap->| item 1
<BLANKLINE>
<BLANKLINE>
**item 2**
<BLANKLINE>
some indented item
<BLANKLINE>
indented item body filled with stuff.
indented item body filled with stuff.
<BLANKLINE>
.. Source: |<-sn1p->| item 2
<BLANKLINE>
<BLANKLINE>
item 2
some indented item
<BLANKLINE>
indented item body filled with stuff.
indented item body filled with stuff.
<BLANKLINE>
.. Source: |<-sn3p->| item 2
<BLANKLINE>
item 1
some item
<BLANKLINE>
item body filled with stuff.
item body filled with stuff.
<BLANKLINE>
.. Source: |<-sn3p->| item 1
<BLANKLINE>
<BLANKLINE>
:item 2:
some indented item
<BLANKLINE>
indented item body filled with stuff.
indented item body filled with stuff.
<BLANKLINE>
.. Source: |<-sn5p->| item 2
<BLANKLINE>
:item 1:
some item
<BLANKLINE>
item body filled with stuff.
item body filled with stuff.
<BLANKLINE>
.. Source: |<-sn5p->| item 1
<BLANKLINE>
<BLANKLINE>
item 2
some indented item
<BLANKLINE>
indented item body filled with stuff.
indented item body filled with stuff.
<BLANKLINE>
.. Source: |<-sn4p->| item 2
<BLANKLINE>
:item 2:
some indented item
<BLANKLINE>
indented item body filled with stuff.
indented item body filled with stuff.
<BLANKLINE>
.. Source: |<-sn6p->| item 2
<BLANKLINE>
load
(file_or_name)[source]¶Load document from file.
Parameters: | file_or_name – file handle or filename. |
---|