AsciiDoc Builder and Writer for Sphinx (asciidoc)

Introduction

Sphinx is used to build documentation from reST source files using Docutils. While there are many Sphinx output writers, such as html, ePub, and LaTex, there has been no conversion tool available to convert Sphinx based reST documentation to asciidoc files. Some of the open source projects, such as Pandoc, do not understand most of the Sphinx directives and are only able to proceed the simple reST format.

The following is my attempt to write an AsciiDoc extension for Sphinx and Docutils that would be able to serve as a builder and writer for Sphinx, as well as a simple reST to AsciiDoc convertor.

This required Python 3.6+.

Standalone usage

You can also use the ./asciidoc/writer.py as a simple convertor of single reST files based on docutils reST format.

To convert a reST file to asciidoc:

python writer.py file.rst

When the script finishes, it creates a new asciidoc file with the same name and the .adoc extension.

Current status

The extension is now a 1.0.0 version. It understands the majority of the Docutils markup and produces a usable asciidoc format, that can be processed with Asciidoctor. However, there are some issues that have not been solved yet, since Asciidoctor does not support similar functionality, or this funcionality is not possible due to Asciidoctor's architecture. There might be improvements in the future.

Note

The conversion may fail because of NotImplemented Error that is caused when the convertor does not understand how to interpret a Sphinx directive. Some of the nodes are only partially implemented. They do not throw out an error, but they do not know how to convert the content either. Instead, they pass the content as plain text and wrap it with the name of the directive, so that users know where the conversion fails. If you experience such troubles, please report this in the issues of this Github project and describe which directive is not rendered and how do you think it should be rendered in asciidoc or how should the html rendering from Asciidoctor look like.

Known issues

Unknown node types

• abbr: AsciiDoc doesn’t have an equivalent and the base docutils doesn’t have a text role for this either, so it’ll throw an error.

• address

Nested indented blockquotes

This will nest a whole new blockquote, which doesn’t work. Should just indent the contents, after the 1st level.

Footnotes position

Intentionally, footnotes get converted into AsciiDoc document attributes and referenced in the text. This only works if the doc references are defined before they’re used, so you’d generally put them at the start. However, because of the way the converter works, they’ll end up wherever they were in the reST document - possibly at the bottom. You might need to move them.

Footnotes have leading newline

The footnotes have a leading newline that will need to be removed manually before they will work properly.

Converted Toctree includes chapters twice

Sphinx uses the .. toctree:: directive to collect single rst files and create a complete book to present on the web page. Asciidoctor is not capable of something similar, so those links were replaced by include directives. A problem is, that those includes are sometimes used more than once, first in the master file and then in the submaster files. In order to get proper results, you have to edit the master file and delete includes that include files from submaster files to get rid of duplications. Alternatively, you can delete all includes from any subfiles and only leave those in the master file.

Referencing to target files instead to IDs

In Sphinx, you can either send a reference to a target (represented by an ID) or to a source file. The result will be similar. On the web, both references will bring you to a given location. The :doc: reference will point towards the beginning of the text provided by the source file. Asciidoc does not use anything like that and I have not been able to find a complete solution for this issue yet. Now, the convertor creates false reference directives that you have to replace manually or programatically. You can find those references because in their definition, the string #fileref has been placed.

reST markup conflicts with Asciidoc markup

Sometimes, especially if you want to show pieces of reST code and use a code block, the markup will not be translated, but rather gets transfered directly into the asciidoc files where it conflicts with Asciidoctor, rendering erroneously. If you experience such problems, you have to use escape characters manually in the resulting asciidoc files.

Future improvements

In the future:

1. reported issues should be fixed, whenever somebody experiences such an error or a new directive will appear in Sphinx,

2. try to solve the known issues to make the translation work flawlessly

3. implement the not yet implemented Sphinx and Docutils nodes, so that the AsciiDoc files use all possible features of the original reST and Sphinx format.

Installing the sphinx_asciidoc package

The package is in PyPI. To install it:

pip3 install sphinx_asciidoc

Now, you should be able to use it.

Using the asciidoc builder

When building the documentation from the source files, choose the asciidoc builder with the -b option:

sphinx-build -b asciidoc ./source ./build

The built documentation is placed in the ./build/asciidoc directory.

Disclaimer

You can freely use the software, but you should be aware that there might problems arise that would need your manual assistance to make the translation error free. Always check that the files have been properly converted before you publish your content.