add asciidoc support

[fallenpegasus]

Please add AsciiDoc support to ReadTheDocs

AsciiDoc is a document markup language similar to Markdown.

http://asciidoctor.org/docs/what-is-asciidoc/
http://asciidoctor.org/docs/what-is-asciidoc/#who-s-using-asciidoc

It has, however, a couple of significant advantages over Markdown. One is that it’s significantly more powerful, with features like table support. Another is that it’s much better standardized; instead of having several dozen rather divergent implementations it has only two, and those two do an excellent job of implementing effectively the same markup language.

Who is using AsciiDoc?
http://asciidoctor.org/docs/what-is-asciidoc/#who-s-using-asciidoc

[humitos]

This issue is being marked as Community Effort since the core team doesn't have enough resources to work on this issue. You can read more information on our philosophy around supporting Read the Docs as an open source and volunteer run effort here: http://docs.readthedocs.io/en/latest/open-source-philosophy.html

[agjohnson]

@fallenpegasus Which is more important, Asciidoc the markup spec, or Asciidoc the tool?

We've talked about asciidoc support in the past. Asciidoc as a markup format is much more likely to be supported than Asciidoc the tooling. We have tried to support multiple tooling, with Mkdocs, and I wouldn't go down this path again. This introduced a disparity between our user experience and feature sets, and the core team doesn't have the resources to future split up our efforts further.

If the spec is more important -- that is, you could use Asciidoc + Sphinx -- I've been exploring supporting alternative formats through docutils. I tried to poke around python asciidoc module in the past, and didn't come across something that provided an AST i could traverse.

[ericholscher]

Going to close this, as any support for asciidoc would be in a third party project, not Read the Docs itself. This was also brought up in #17 and #533 -- as @agjohnson mentioned, we'd love to have support for it in Sphinx, and support it that way.

[boegel]

Any idea if using https://pypi.org/project/sphinx-asciidoc would work to use asciidoc as a format for documentation hosted on readthedocs?

[stsewd]

@boegel looks like it should work!

[ericholscher]

I believe that extension is doing RST->Asciidoc, instead of Asciidoc->RST. You need something like recommonmark but for asciidoc, which creates the RST doctree from the Asciidoctor parser.