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.

@startuml
package "Common Tasks" as CT {
  object "Task 1" as CO1 {
  }
  object "Task 2" as CO2 {
  }
  object "Task 3" as CO3 {
  $ sudo passwd @user@
  > @passwd@
  > @passwd@
  }
  CO1 -[hidden]> CO2
  CO2 -[hidden]> CO3
}

package "Process 1" as P1 {
  object "Task 1" as P1O1 {
  $ sudo passwd nu
  > h4t=87
  > h4t=87

  $ sudo chsh -s /bin/bash nu
  }
  object "Task 2" as P1O2 {
  }
  object "Task 3" as P1O3 {
  common task 1
  }
  P1O1 -[hidden]> P1O2
  P1O2 -[hidden]> P1O3
  P1O1 --|> CO3
  P1O3 --|> CO1
}

package "Process 2" as P2 {
  object "Task 1" as P2O1 {
  }
  object "Task 2" as P2O2 {
  common task 1
  }
  object "Task 3" as P2O3 {
  common task 2
  }
  P2O1 -[hidden]> P2O2
  P2O2 -[hidden]> P2O3
  P2O2 --|> CO1
  P2O3 --|> CO2
}

P1 *-- CT
P2 *-- CT

@enduml

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

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

  2. the first section title:

    .. \|<-snip->|
    
    --------------------------------------------------
    :rem:`||:sec:||`\ Snippet Section Title
    --------------------------------------------------
    
    .. \|<-snip->|
    
  3. 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.

  1. item 2
  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.