AsciiDoc3 API
=============

'asciidoc3api' -- a Python API module for 'AsciiDoc3'.


Introduction
------------
The 'asciidoc3api' module implements a Python API for AsciiDoc3. It
allows you to set `asciidoc3(1)` program options, compile an AsciiDoc3
source file and then interrogate the results.  The `asciidoc3api.py`
module file contains the `AsciiDoc3API` wrapper class for
`asciidoc3.py`.

.Benefits
- Stable API Shields the user from the undocumented and possibly
  volatile `asciidoc3.py` internals.
- Easier to use and more flexible than the alternative of running
  `asciidoc3(1)` as a separate process.
- Executes inside your application (better performance than running
  separate `asciidoc3(1)` command processes).


Using asciidoc3api
------------------
To use the API just drop the `asciidoc3api.py` file into your
application directory, import it and use the `AsciiDoc3API` class.  The
only requirement is that a compatible version of 'AsciiDoc3' is already
installed -- simple, no setuptools to run, no non-standard library
dependencies.

You can find `asciidoc3api.py` in your AsciiDoc3 distributions main directory.


The following minimal example compiles `mydoc.txt` to `mydoc.html`:

-------------------------------------------------------------------------------
from asciidoc3api import AsciiDoc3API
asciidoc3 = AsciiDoc3API()
asciidoc3.attributes['data-uri'] = '' <1>
asciidoc3.execute('mydoc.txt')
-------------------------------------------------------------------------------
<1> Example how to provide an attribute. 

[NOTE]
.PyPI, venv (Windows or GNU/Linux and other POSIX OS)
Unfortunately, sometimes (not always - depends on your directory-layout, operating system etc.) AsciiDoc3 cannot find the 'asciidoc3' module when you installed via venv and/or PyPI. +
The solution: Import the module by providing the full path:

-------------------------------------------------------------------------------
from asciidoc3api import AsciiDoc3API
asciidoc3 = AsciiDoc3API('/full/path/to/asciidoc3.py') <1>
asciidoc3.execute('mydoc.txt')
-------------------------------------------------------------------------------
<1> Example: '/home/username/venv_dir/lib/python3.7/site-packages/asciidoc3/asciidoc3.py'




