Support AsciiDoctor

[ericholscher]

I really like what AsciiDoctor is doing, and I think that they follow the philosophical model that we support enough to add support.

Asciidoctor

http://asciidoctor.org

It is a similar project to Sphinx, allowing you to take asciidoc files and generate HTML and other formats from them.

Deployment

Asciidoctor is a ruby project. I don't know the best way to handle dealing with ruby dependencies. I'm not sure how they handle extensions, but we will likely need to support some kind of virtualenv equivalent for ruby, rvm or rbenv seem like the most popular.

Builder

Adding support to RTD will require having a builder for Asciidoctor. It should be pretty simple to integrate it into the existing RTD workflow, where on project import you choose "AsciiDoctor" as the "Documentation Type".

De-sphinxification

There are places where Sphinx specific code and logic has crept out of the backend builders and into the main code paths. We will need to remove that to support Asciidoctor. Specifically things around conf.py files and other bits and pieces.

[AlexCzar]

+1 on this. We use asciidoctor + awestruct to create documentation for our internal projects, but it requires tremendous effort (we're not front-end developers, so html/js are aliens and ruby is a strange beast) to customize templates and scripts for documentation-friendly design.

[mojavelinux]

+1

I haven't forgotten about this issue. I've been busy lately working more flexibility into the Asciidoctor processor, which will come in handy here, and to get the 1.5.0 release ready. As soon as 1.5.0 is out, I think it will be the right time to start tackling this integration.

[bobblanchett]

+1 asciidoc support for rtd please

[mojavelinux]

I did a write-up about this on the Asciidoctor mailinglist with a suggestion of what steps to take first.

http://discuss.asciidoctor.org/Read-The-Docs-Integration-td2018.html

As I mentioned there, the static site generates that I recommend evaluating are dexy and middleman. Keep in mind that while Asciidoctor is written in Ruby, it also runs on the JVM (AsciidoctorJ) and in JavaScript (Asciidoctor.js). So we have several ways of invoking it.

[leonard84]

+1

[tduchateau]

+1

[juherr]

+1

[ericholscher]

Closing this issue, because it isn't on our current roadmap.

[mojavelinux]

@ericholscher Perhaps you could layout the requirements that would need to be met so that if someone in the community wanted to work on it, they would know where to aim. I've found that leaving behind some direction is the best way to defer a feature entirely to a community effort. I'd be happy to chime in if I understood what information is needed.

[akhayyat]

I am interested in using RTD with an asciidoctor backend. Is there any future to this direction? I'd reiterate @mojavelinux's inquiry about what'd constitute a minimal workable setup.

[rmpestano]

+1

[AlexCzar]

The issue is unfortunately closed, my team moved on to a home built solution, which is subpar to RTD, but we do not have much time to invest into documentation hosting.

[rmpestano]

I see and understand, maybe its time for "readthedoctor".

[ericholscher]

We are happy to accept a patch that adds support. However, nobody has given us any good information on how we can support it in this ticket, and it's currently not a priority for us.

[ericholscher]

I should note, that we would only consider adding Asciidoc support to Sphinx, not supporting another "documentation framework" of sorts. We tried this with Markdown (Mkdocs) and it has been a maintenance nightmare. If you wanted to further this work, being able to generate an Asciidoc AST into a docutils AST (or JSON) would be the best place to start.

[ericholscher]

https://github.com/rtfd/recommonmark is the implementation of this for Markdown (Commonmark)

[sengopal]

+1

[jamesread]

Is this of use? https://github.com/lruzicka/sphinx_asciidoc

[ericholscher]

Just a note that we can now support this with our new build customization feature: https://docs.readthedocs.io/en/latest/build-customization.html#override-the-build-process

Only 9 years from the initial issue... @mojavelinux Not sure if this is still of interest, but we'd love to work with y'all to get RTD nicely integrated into Antora for deployment with our search & versioning.

[man-chi]

+1 yes , the support of asciidoc in readthedocs is exciting! thanks for the effort on integration

[humitos]

we'd love to work with y'all to get RTD nicely integrated into Antora for deployment with our search & versioning.

With the introduction of the new Read the Docs Addons, search and versioning should be working by default when building the documentation using "Build customization" via build.commands as @ericholscher mentioned.

I'd love to hear if anybody was able to deploy their documentation with AsciiDoctor and if it's working as expected. Any feedback is appreciated here. Feel free to open a new issue if you consider as well 👍🏼

[man-chi]

to my understanding asciidoc is only support if we build and install on-premise cloud but not on readthedocs SaaS platform, correct?

[humitos]

No, you should be able to use AsciiDoc on Read the Docs SaaS platform without issues. I built a small example using AsciiDoctor that's hosted on Read the Docs at https://test-builds.readthedocs.io/en/asciidoctor/

These are the build.commands that I've used on Read the Docs: https://beta.readthedocs.org/projects/test-builds/builds/21989207/#203831360--7

[man-chi]

is it possible to use diagram extension in asciidoc syntax like plantuml? https://docs.asciidoctor.org/diagram-extension/latest/diagram_types/plantuml/

[humitos]

@man-chi I haven't use plantuml, but everything that normally works on Asciidoctor when building locally should also work on Read the Docs with no issues.

[mojavelinux]

npm install -g asciidoctor

If you choose to use Asciidoctor.js, then you'll need to use Asciidoctor Kroki to get diagram support via Kroki. If you choose to use Asciidoctor instead (the RubyGem), then you can use Asciidoctor Diagram (which is also a RubyGem).

[man-chi]

thanks for your great help. I managed to get asciidoc running successfully.

but there is no full site structure with side bar and search bar available. I used to use antora. is it possible to setup antora https://docs.antora.org running in .readthedocs.yml , I have been trying but in vain.

anyone has setup Antora successfully? any sample .readthedocs.yml? any code example to run a sample site?

should I do the following?

version: "2"
build:
  os: "ubuntu-22.04"
  tools:
    nodejs: "20"
  commands:
    - npm install -g asciidoctor asciidoctor-kroki
    - npm i -D -E @antora/cli@3.1 @antora/site-generator@3.1
    - npm i -g @antora/cli@3.1 @antora/site-generator@3.1
    - npx antora --fetch docs/antora-playbook.yml`

[humitos]

Hi @man-chi! I created a small example using the Quickstart guide from Antora and built it on Read the Docs:

• Demo project living on Read the Docs: https://test-builds.readthedocs.io/en/antora/component-b/2.0/index.html
• readthedocs.yaml for the build: https://beta.readthedocs.org/projects/test-builds/builds/23266677/#217702820--1

I hope that helps! 🎉

[man-chi]

@humitos I have tried your antora example, and it works perfectly. you are so kind!! I love readthedocs community and the excellent documentation solution! (I was also given up after struggling for the past few days :-P

I am planning to promote readthedocs as a standard documentation platform to all my biz partners and development teams in Taiwan!!!

million thanks for your prompt and helpful response !!

[ericholscher]

Hi @man-chi! I created a small example using the Quickstart guide from Antora and built it on Read the Docs:

• Demo project living on Read the Docs: https://test-builds.readthedocs.io/en/antora/component-b/2.0/index.html
• readthedocs.yaml for the build: https://beta.readthedocs.org/projects/test-builds/builds/23266677/#217702820--1

I hope that helps! 🎉

We should put this in a doc guide or similar, just so we have a landing page for the basic information here.

[man-chi]

love to see if we could move this test build code as a rtd template like the tutorial template

[ericholscher]

@man-chi If you'd like to contribute here, we have example projects that could be a good place to do something like this! https://docs.readthedocs.io/en/stable/examples.html

[man-chi]

yes definitely, I will love to contribute the rtd template, I have also manage to get the lunr search bar and Vega diagram working. 

I will look into it

[ericholscher]

@man-chi Great -- do you have a link to your project, just so we can see what you're doing?

[man-chi]

the docs is still working in process, I will be changing very much in the next few days (just for your preview). the URL will be changed as well. https://example-antora-basic.readthedocs.io/en/latest/main/index.html

I am also tidying up an sample version for readthedocs template. so far, example for asciidoc, kroki, vega and C4 / UML

[man-chi]

do you think it will be helpful to include any example of asciidoc, kroki, vega and C4 / UML in the RTD template?

[ericholscher]

I think the main thing is probably just a simple "starter" project for folks who want to use Antora -- they might not want the additional stuff, but could be worth pointing to your project as a more complex example for folks who want it.

[mojavelinux]

I commented on the PR with some proposed improvements to the build config.

[man-chi]

@ericholscher / @mojavelinux / @humitos

I have created a ticket requesting to contribute my tutorial template (for asciidoc) to readthedoc community, kindly let me know the necessary steps to complete PR, happy to adjust anything according to RTD policy.

https://github.com/readthedocs/readthedocs.org/issues/11088

[mojavelinux]

You can find the comments I left here: https://github.com/readthedocs/test-builds/commit/5118fdf697c5df0f3258a108410f58a1a9108cea

[humitos]

If you choose to use Asciidoctor instead (the RubyGem), then you can use Asciidoctor Diagram (which is also a RubyGem).

BTW, we are adding support for Ruby in our next deploy (Tuesday 6th), so you will be able to use the Ruby implementation instead of the JavaScript one, if you want.

[man-chi]

@humitos may I know the key difference between ruby and js implementation? any advantages if I change from js to ruby?

[mojavelinux]

Asciidoctor.js is mostly intended for using it in the browser or JavaScript-based application like Antora. If you aren't doing either of those things, then Asciidoctor (Ruby) is the preferred tool. Asciidoctor.js is the same code as Asciidoctor with a porcelain API around it, but it doesn't offer as many extensions (since not all extensions have been or can even be transpiled to JavaScript).

[man-chi]

I would like to try out the ruby implementation coming tue

[man-chi]

@man-chi If you'd like to contribute here, we have example projects that could be a good place to do something like this! https://docs.readthedocs.io/en/stable/examples.html

@ericholscher can you kindly review and approve my contribution for asciidoc example? https://github.com/readthedocs/readthedocs.org/pull/11091

[ericholscher]

@man-chi Looks great -- I've merged #11091. Thanks again 🎉