Deploying to gh-pages from @ d0a01e1 🚀

api.md.template

@@ -0,0 +1,381 @@
+API Reference
+================================================================================
+
+``` python
+import pandoc
+from pandoc.types import *
+```
+
+`pandoc`
+--------------------------------------------------------------------------------
+
+
+??? note "`read(source=None, file=None, format=None, options=None)`"
+    Read a source document.
+
+    The source document must be specified by either `source` or `file`.
+    Implicitly, the document format is inferred from the filename extension
+    when possible[^heuristics], otherwise the markdown format is assumed
+    by default; the input format can also be specified explicitly.
+    Extra options can be passed to the pandoc command-line tool.
+
+
+    [^heuristics]: refer to [Pandoc's heuristics](https://github.com/jgm/pandoc/blob/master/src/Text/Pandoc/App/FormatHeuristics.hs) for the gory details of this inference.
+
+    <h5>Arguments</h5>
+
+
+      - `source`: the document content, as a string or as utf-8 encoded bytes.
+
+      - `file`: the document, provided as a file or filename.
+
+      - `format`: the document format (such as `"markdown"`, `"odt"`, `"docx"`, `"html"`, etc.)
+
+        Refer to [Pandoc's README](https://github.com/jgm/pandoc#pandoc) for
+        the list of supported input formats.
+
+      - `options`: additional pandoc options (a list of strings).
+
+        Refer to [Pandoc's user guide](https://pandoc.org/MANUAL.html) for a
+        complete list of options.
+
+    <h5>Returns</h5>
+
+      - `doc`: the document, as a `Pandoc` object.
+
+    <h5>Usage</h5>
+
+
+    Read documents from strings:
+
+    ``` pycon
+    >>> markdown = "Hello world!"
+    >>> pandoc.read(markdown)
+    Pandoc(Meta({}), [Para([Str('Hello'), Space(), Str('world!')])])
+    >>> html = "<p>Hello world!</p>"
+    >>> pandoc.read(html, format="html")
+    Pandoc(Meta({}), [Para([Str('Hello'), Space(), Str('world!')])])
+    ```
+
+    Read documents from files:
+
+    ``` pycon
+    >>> filename = "doc.html"
+    >>> with open(filename, "w", encoding="utf-8") as file:
+    ...     _ = file.write(html)
+    >>> pandoc.read(file=filename) # html format inferred from filename
+    Pandoc(Meta({}), [Para([Str('Hello'), Space(), Str('world!')])])
+    >>> file = open(filename, encoding="utf-8")
+    >>> pandoc.read(file=file, format="html") # but here it must be explicit
+    Pandoc(Meta({}), [Para([Str('Hello'), Space(), Str('world!')])])
+    ```
+
+    Use extra pandoc options:
+
+    ``` pycon
+    >>> pandoc.read(markdown, options=["-M", "id=hello"]) # add metadata
+    Pandoc(Meta({'id': MetaString('hello')}), [Para([Str('Hello'), Space(), Str('world!')])])
+    ```
+
+
+??? note "`write(doc, file=None, format=None, options=None)`"
+    Write a pandoc document (or document fragment) to a file and return its contents.
+
+
+    Inline document fragments are automatically wrapped into a `Plain` 
+    blocks; block document fragments are automatically wrapped into
+    a `Pandoc` element with no metadata. 
+
+    Implicitly, the document format is inferred from the filename extension
+    when possible[^heuristics], otherwise the markdown format is assumed
+    by default; the output format can also be specified explicitly.
+    Extra options can be passed to the pandoc command-line tool.
+
+
+    <h5>Arguments</h5>
+
+      - `doc`: a `Pandoc` object or a document fragment 
+        (`Inline`, `[Inline]`, `MetaInlines`, 
+         `Block`, `[Block]` or `MetaBlocks`).
+
+      - `file`: a file, filename or `None`.
+
+      - `format`: the document format (such as `"markdown"`, `"odt"`, `"docx"`, `"html"`, etc.)
+
+        Refer to [Pandoc's README](https://github.com/jgm/pandoc#pandoc) for
+        the list of supported output formats.
+
+      - `options`: additional pandoc options (a list of strings).
+
+        Refer to [Pandoc's user guide](https://pandoc.org/MANUAL.html) for a
+        complete list of options.
+
+    <h5>Returns</h5>
+
+      - `output`: the output document, as a string or as a byte sequence.
+
+        Bytes are only used for binary output formats (doc, ppt, etc.).
+
+    <h5>Usage</h5>
+
+    Write documents to markdown strings:
+
+    ``` pycon
+    >>> doc = pandoc.read("Hello world!")
+    >>> doc
+    Pandoc(Meta({}), [Para([Str('Hello'), Space(), Str('world!')])])
+    >>> print(pandoc.write(doc))  # doctest: +NORMALIZE_WHITESPACE
+    Hello world!
+    ```
+
+    Write document fragments to markdown strings:
+
+    ``` pycon
+    >>> md = lambda elt: print(pandoc.write(elt))
+    >>> md(Str("Hello!")) # doctest: +NORMALIZE_WHITESPACE
+    Hello!
+    >>> md([Str('Hello'), Space(), Str('world!')]) # doctest: +NORMALIZE_WHITESPACE
+    Hello world!
+    >>> md(Para([Str('Hello'), Space(), Str('world!')])) # doctest: +NORMALIZE_WHITESPACE
+    Hello world!
+    >>> md([ # doctest: +NORMALIZE_WHITESPACE
+    ...     Para([Str('Hello'), Space(), Str('world!')]),
+    ...     Para([Str('Hello'), Space(), Str('world!')])
+    ... ])
+    Hello world!
+    <BLANKLINE>
+    Hello world!
+    >>> md(MetaInlines([Str('Hello'), Space(), Str('world!')])) # doctest: +NORMALIZE_WHITESPACE
+    Hello world!
+    >>> md(MetaBlocks([ # doctest: +NORMALIZE_WHITESPACE
+    ...     Para([Str('Hello'), Space(), Str('world!')]),
+    ...     Para([Str('Hello'), Space(), Str('world!')])
+    ... ]))
+    Hello world!
+    <BLANKLINE>
+    Hello world!
+    ```
+
+    Use alternate (text or binary) output formats:
+
+    ``` pycon
+    >>> output = pandoc.write(doc, format="html") # html output
+    >>> type(output)
+    <class 'str'>
+    >>> print(output)
+    <p>Hello world!</p>
+    <BLANKLINE>
+    >>> output = pandoc.write(doc, format="odt")
+    >>> type(output)
+    <class 'bytes'>
+    >>> output # doctest: +ELLIPSIS
+    b'PK...'
+    ```
+
+
+    Write documents to files:
+
+    ``` pycon
+    >>> _ = pandoc.write(doc, file="doc.md")
+    >>> open("doc.md", encoding="utf-8").read()
+    'Hello world!\n'
+    >>> _ = pandoc.write(doc, file="doc.html")
+    >>> open("doc.html", encoding="utf-8").read()
+    '<p>Hello world!</p>\n'
+    >>> _ = pandoc.write(doc, file="doc.pdf")
+    >>> open("doc.pdf", "rb").read() # doctest: +ELLIPSIS
+    b'%PDF...'
+    ```
+
+    Use extra pandoc options:
+
+    ``` pycon
+    >>> output = pandoc.write(
+    ...     doc, 
+    ...     format="html", 
+    ...     options=["--standalone", "-V", "lang=en"]
+    ... )
+    >>> print(output) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
+    <!DOCTYPE html>
+    <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+    ...
+    <body>
+    <p>Hello world!</p>
+    </body>
+    </html>
+    ```
+
+??? note "`iter(elt, path=False)`"
+
+    Iterate on document elements in document order.
+
+    <h5>Arguments</h5>
+
+      - `elt`: a pandoc item (or more generally any Python object),
+
+      - `path`: a boolean; defaults to `False`.
+
+    <h5>Returns</h5>
+
+      - `iterator`: a depth-first tree iterator.
+
+      - `elt_path` (when `path==True`): a list of `(elt, index)` pairs. 
+
+    <h5>Usage</h5>
+
+    This iterator may be used as a general-purpose tree iterator
+
+    ``` pycon
+    >>> tree = [1, [2, [3]]]
+    >>> for elt in pandoc.iter(tree):
+    ...     print(elt)
+    [1, [2, [3]]]
+    1
+    [2, [3]]
+    2
+    [3]
+    3
+    ```
+
+    Non-iterable objects yield themselves:
+
+    ``` pycon
+    >>> root = 1
+    >>> for elt in pandoc.iter(root):
+    ...     print(elt)
+    1
+    ```
+
+    But it is really meant to be used with pandoc objects:
+
+    ``` pycon
+    >>> doc = Pandoc(Meta({}), [Para([Str('Hello'), Space(), Str('world!')])])
+    >>> for elt in pandoc.iter(doc):
+    ...     print(elt)
+    Pandoc(Meta({}), [Para([Str('Hello'), Space(), Str('world!')])])
+    Meta({})
+    {}
+    [Para([Str('Hello'), Space(), Str('world!')])]
+    Para([Str('Hello'), Space(), Str('world!')])
+    [Str('Hello'), Space(), Str('world!')]
+    Str('Hello')
+    Hello
+    Space()
+    Str('world!')
+    world!
+    ```
+
+    Two gotchas: characters in strings are not iterated (strings are considered
+    "atomic")
+
+    ``` pycon
+    >>> root = "Hello world!"
+    >>> for elt in pandoc.iter(root):
+    ...     print(elt)
+    Hello world!
+    ```
+
+    and dicts yield their key-value pairs (and not only their keys):
+
+    ``` pycon
+    >>> root = {"a": 1, "b": 2}
+    >>> for elt in pandoc.iter(root):
+    ...      print(elt)
+    {'a': 1, 'b': 2}
+    ('a', 1)
+    a
+    1
+    ('b', 2)
+    b
+    2
+    ```
+
+    Use `path=True` when you need to locate the element in the document.
+    You can get the element parent and index within this parent as `path[-1]`,
+    the grand-parent and the index of the parent within the grand-parent 
+    as `path[-2]`, etc. up to the document root.
+
+    ``` pycon
+    >>> doc = Pandoc(Meta({}), [Para([Str('Hello'), Space(), Str('world!')])])
+    >>> world = Str("world!")
+    >>> for elt, path in pandoc.iter(doc, path=True): # find the path to Str("world!")
+    ...     if elt == world:
+    ...         break
+    >>> for elt, index in path:
+    ...     print(f"At index {index} in {elt}:")
+    ... else:
+    ...     print(world)
+    At index 1 in Pandoc(Meta({}), [Para([Str('Hello'), Space(), Str('world!')])]):
+    At index 0 in [Para([Str('Hello'), Space(), Str('world!')])]:
+    At index 0 in Para([Str('Hello'), Space(), Str('world!')]):
+    At index 2 in [Str('Hello'), Space(), Str('world!')]:
+    Str('world!')
+    ```
+
+    <h5>See also</h5>
+
+    Refer to the [Tree iteration section](../iteration#tree-iteration).
+
+
+??? note "`configure(auto=False, path=None, version=None, pandoc_types_version=None, read=False, reset=False)`"
+
+    <h5>Arguments</h5>
+
+      - `auto`: a boolean; defaults to `False`; set to `True` to
+        infer the configuration from the `pandoc` in your path.
+
+      - `path`: the path to the pandoc executable, such as `"/usr/bin/pandoc"`.
+
+      - `version`: the `pandoc` command-line tool version, such as `"2.14.2"`.
+
+      - `pandoc_types_version`: the [`pandoc-types`](https://hackage.haskell.org/package/pandoc-types)
+         version, such as `"1.22.1"`.
+
+      - `read`: a boolean; defaults to `False`. Return the configuration dictionary.
+
+      - `reset`: a boolean; defaults to `False`. Delete the current configuration.
+
+    <h5>Returns</h5>
+
+      - `configuration` (if `read==True`): the configuration dictionary,
+        with entries `"auto"`, `"path"`, `"version"` and "`pandoc_types_version`".
+
+    <h5>Usage</h5>
+
+    The configuration step is triggered when you import `pandoc.types` or
+    call `pandoc.read` or `pandoc.write` and will automatically infer the
+    configuration from the `pandoc` executable found in the path (or fails).
+
+    ``` pycon
+    >>> config = pandoc.configure(read=True)
+    >>> config # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
+    {'auto': True, 
+     'path': ..., 
+     'version': '3.2.1', 
+     'pandoc_types_version': '1.23.1'}
+    ```
+    To avoid this, call `pandoc.configure(...)` yourself beforehand.
+    Alternatively, select manually your pandoc executable afterwards:
+
+    ``` pycon
+    >>> pandoc.configure(reset=True)
+    >>> pandoc.configure(read=True) is None
+    True
+    >>> config["auto"] = False
+    >>> pandoc.configure(**config)
+    >>> pandoc.configure(read=True) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
+    {'auto': False, 
+     'path': ..., 
+     'version': '3.2.1', 
+     'pandoc_types_version': '1.23.1'}    
+    ```
+
+    <h5>See also</h5>
+
+    Refer to the [Configuration section](../configuration).
+
+
+`pandoc.types`
+--------------------------------------------------------------------------------
+
+${types_documentation}