AsciiDoc support

[senier]

It would be great if readme_renderer supported AsciiDoc natively. It has some very neat features and it would be nice to use the same format for our README as well as for the rest of the documentation. There is AsciiDoc3 to handle AsciiDoc in Python.

[chrysle]

I'll work on this.

[chrysle]

There is one complication I'd like to discuss before implementing anything. Related: asciidoctor/asciidoctor#3340

The Python port of AsciiDoc, AsciiDoc.py (legacy processor, asciidoc3 is based on that and was just ported earlier to Python 3. Also it seems to have fallen behind the better developed asciidoc.), isn't totally compliant with the latest AsciiDoctor language spec - although that is on their roadmap.

However with this in mind I don't see any alternative to just creating the renderer on top of the Python implementation and pointing out it only supports the spec published by the AsciiDoc.py project until they have caught up.

@di @miketheman What do you think?

[lfvjimisola]

There has been a discussion about this in the AsciiDoc ZulipChat forum with @mojavelinux among others.

The lack of an updated python implementation is a clear issue. The is a Language Specification is in progress and once that is finalized implementations in other languages can be implemented.

I'm not sure how much difference there is between AsciiDoc.py and AsciiDoctor, but work case is that AsciiDoc.py is a AsciiDoc-flavor nowadays.

[chrysle]

Gentle ping on this @pypa/readme_renderer-committers.

[webmaven]

I am working on a specification-compliant implementation: https://pypi.org/project/asciidoctrine/

I have a couple of projects that depend on it already:
https://github.com/webmaven/asciidocstring
https://github.com/webmaven/asciidoctest

I am also trying to contribute to completing the spec and expanding the TCK:
https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/merge_requests/57
https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-tck/-/merge_requests/42

The lack of a completed specification is an issue and likely to be one for a while given the current pace, but I figure I won't go too wrong simply emulating Asciidoctor to cover any un- or under-specified features.

[webmaven]

A bit of extra context: PyPI currently rejects uploads when the README.* file's media type is undeclared or is declared as anything other than one of these specific media types (AKA content-types):

• text/plain
• text/x-rst
• text/markdown

Currently I am uploading packages that have README.adoc files to PyPI by stating the content-type of the file is text/plain, but I'd prefer to use text/asciidoc even if no processing is currently done and the file continues to be treated as text/plain for the time being.

The text/asciidoc media type has been accepted by IANA as a provisional standard media type: https://www.iana.org/assignments/provisional-standard-media-types

On whatever illustrious day that PyPI does implement rendering AsciiDoc to HTML, it could do so retroactively for those few packages that declared their README.adoc to be content-type="text/asciidoc" all along.

So, baby steps. @miketheman, Would filing a "provisional support" issue for the text/asciidoc media-type (that simply enables it to be used without the uploads being rejected) be appropriate?

As a reminder, this is what a README.adoc file currently looks like on PyPI when uploaded as an ostensible text/plain file: https://pypi.org/project/sphinx-asciidoctrine/

What that same README.adoc looks like on GitHub:
https://github.com/webmaven/sphinx-asciidoctrine

What the public docs (on GitHub pages) look like (using the plugin on it's own Sphinx documentation, so it is self-hosting in that regard):
https://webmaven.github.io/sphinx-asciidoctrine/