17. Document Snippets¶

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.

17.1. Document Snippet Definition¶

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->|

17.1.1. Item Prefix¶

An item prefix is a non-empty string at the beginning of a line, consisting of

optional leading whitespace
a dash -, plus +, asterisks *, hash dot #., integer dot 1., or space ␣
a minimum of 1 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

17.1.2. Item Prefix Snippet Examples¶

>- |<-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.

17.1.3. Document Snippet Names¶

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.

17.1.4. Document Snippet Flags¶

The first argument of the starting .. \|<-snip->| marker is evaluated as a string of flags consisting of:

a minus sign -: The snippet is removed from document body, when parsing.

17.1.5. Document Snippet Examples¶

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->|

17.2. Snippet Tag Substitutions¶

The document snippet tags |<-snip->| and |<-snap->| are defined as substitutions, which are effectively blank:

.. |<-snip->| replace:: \ :rem:`x`
.. |<-snap->| replace:: \ :rem:`x`

17.3. Document Snippet References¶

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.

17.3.1. Item Prefix Reference¶

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

17.3.2. Item Prefix Reference Examples¶

Here are some live examples from the item snippets defined above. They are actually expanded in the resolved version of this document.

item 2
item 1

item 1

item 2

17.3.3. Reference Features¶

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

17.3.4. Reference Feature Examples¶

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

17.3.5. Reference Headers¶

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.

17.3.6. Reference Examples¶

In the resolved document, the following section is moved from above to here:

Snippet Tag Substitutions

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:

Snippet Tag Substitutions

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:

Snippet Tag Substitutions

Here comes a demoted version of the section …

Snippet Tag Substitutions

17.4. Replacement Facilities¶

See section Replacements in sphinx_doc_snip.py for a details.

17.4.1. Replacement Test¶

In the resolved version, both sides will read laptop-mb:

@hostname@ => laptop-mb

17.5. sphinx_doc_snip.py¶

sphinx_doc_snip.py - process sphinx-doc document snippets.

usage:	sphinx_doc_snip.py [OPTIONS] file-to-process …
or	import sphinx_doc_snip

17.5.1. Options¶

–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)

–pdf 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

17.5.2. Description¶

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.

17.5.2.1. Configuration Files¶

The configuration files

doc/.doc-snip.rc.default
.doc-snip.rc.default
doc/.doc-snip.rc
.doc-snip.rc

are read in that order.

Example:

FORCE=no
FORMAT='{sbase}{sext}'
INCLUDE='
README.txt
README-stations.txt
'
REPLACE='
user=Max Benutzer
user_short=mb
'

17.5.2.2. Replacements¶

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

|:todo:| recursive snippet resolution

17.5.3. Module¶

17.5.4. Automatic Exports¶

>>> 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

17.5.5. Explicit Exports¶

>>> if '__all_internal__' in globals():
...   for ex in __all_internal__:
...     printf(sformat('from {0} import {1}', __name__, ex))

17.5.6. Details¶

class 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.

dump_snippets(file=None)[source]¶

Returns:	self for chaining.

register(doc_or_filename, include=None)[source]¶

Returns:	self for chaining.

resolve(snippets=None, continued=None)[source]¶: Resolve snippets in all registered documents.

class 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>

dump_snippets(file=None)[source]¶: Dump document snippets.

load(file_or_name)[source]¶

Load document from file.

Parameters:	file_or_name – file handle or filename.

map_snippets(include=None)[source]¶: Get document snippets dictionary.

parse(text=None, partition=None)[source]¶: Parse document for document snippets.

register_snippets_with(snippets, include=None)[source]¶

Register document snippets in snippets dict.

Parameters:	snippets – snippets dictionary.

resolve(snippets=None)[source]¶

Resolve snippets in document.

Returns:	`pyjsmo.sections.SectPart` instance with resolved body.
Parameters:	snippets – snippet section dictionary. I None, the document snippets are

class sphinx_doc_snip.Snippet(*args, **kwargs)[source]¶

Snippet section.

Behaves like a standard Section instance until method prepare() is called, which converts the section to a snippet.

dump(file=None)[source]¶: Dump snippet.

prepare(section=None)[source]¶: Prepare snippet.

reset()[source]¶: Reset snippet for new resolution.

class sphinx_doc_snip.Section(*args, **kwargs)[source]¶

Text section.

Behaves like a pyjsmo.sections.Section.

The method resolve() replaces snippet references with snippets.

resolve(snippets)[source]¶: Resolve snippets in section body.

–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)
–pdf	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