How to use AsciiDoc with Python?

Question

The original AsciiDoc processor was written in python, but AsciiDoc evolved in the form of Asciidoctor written in Ruby.

On my search for how to process modern AsciiDoc (the Asciidoctor dialect), I only came across a post that there is an older project to port AsciiDoc to Python 3 (https://github.com/asciidoc/asciidoc/issues/83).

But since the origins of AsciiDoc are in Python, it is hard to find anything useful via google.

So what is currently the best way to process AsciiDoc from within a Python program? Call the Ruby version or commandline processor?

Celaeno

Answer 1

You may use Python3 to go on: you can find the brand-new Python3 port AsciiDoc3 at www.asciidoc3.org and on gitlab.com/asciidoc3/asciidoc3.

All 170 AsciiDoc testcases are passed!

Merman

cool and interesting. I assume this is a port of the old python2 asciidoc and not the ruby based aaciidoctor? – Celaeno

Yes, AsciiDoc3 is the port of 'the old python2' asciidoc to 100% pure Python3 - and has nothing to do with asciidoctor ... – Merman

How does it work? Website does not contain anything meaningful about actualy using this stuff from Python (not via running executable) – Charwoman

To use asciidoc3 or a2x3 through another (python) program just type something like this (or something similar - import module subprocess): ... p = subprocess.Popen(asciidoc3, shell=True, stdin=subprocess.PIPE, stdout=subprocess.PIPE, universal_newlines=True, bufsize=-1) output = p.communicate(...) ... – Merman

@TheGodfather Just stumbled on this. Asciidoc-py3 provides an API module: github.com/asciidoc/asciidoc-py3/blob/master/asciidocapi.py. Supposedly this should also be there in asciidoc3, but I didn't see it in the repo. – Alexina

asciidoctor is not asciidoc. You can write stuff in asciidoctor that asciidoc will not understand. – Harriman

Here's a definitive reference on the differences between the "old" (Python2/Asciidoc.py) and "new" (Ruby/Asciidoctor) syntaxes. "If a feature or attribute isn’t mentioned in the following tables, then it works in Asciidoctor just like it worked in AsciiDoc.py." – Mooncalf