I’m working on the largely mechanical process of translating the existing Dialog manual into Antora.
Antora is a very full-features documentation system; it’s built on Node. The core is Asciidoc, which can be thought of as a super-charged version of Markdown.
I’ve used Antora previously for the documentation of Pedestal.
Antora abounds in useful features, but one of its most basic is versioning. It actually builds a tree of sites, divided by version (versions correspond to specific branches). This works great when code is evolving, as the code changes and documentation changes co-exist.
Antora is highly extensible and customizable, but even out-of-the-box it has nice features, such as a floating page-navigation on the right and inter-page navigation on the left.
I have things configured on Pedestal so that merges in the main GitHub repository trigger a rebuild/republish of the documentation. The same could ultimately be done for Dialog.
We would have to determine an appropriate location to publish to.
Finally, Antora can work against multiple repositories, so we could have a unified documentation hub for both Dialog, but also related things (such as the dialog tools and extensions I’ve also been working on).
Asciidoc seems like a fine choice for the source docs… I have never used it but I know a lot of folks who swear by it.
I’ve never heard of Antora, and have thus no opinion on it, but I’d be up to try it out! Sounds like there’s not much risk of lock-in since the docs themselves are in a standard format.
I’m at the point now where I’m wondering about writing a script to scrape the existing pages to produce the asciidoc (with the expectation of review and revise the output); it’s been a simple, mechanical process to convert, but there’s a lot of pages.
Is it possible to keep the asciidoc files in the repo in a way that they can be easily read and navigated right there on GitHub, while also work well for Antora export?
A quick search at least tells me that there is a subset of asciidoc that is supported by GitHub.
The more generic the source docs the better, of course. Maybe someone, hypothetically, wants to instead export it to some other format using PanDoc for instance.
I strongly believe in keeping the code and docs in the same repo, so that a PR that affects the code can also include doc updates as a single unit of work.
I have also used Sphinx, which is used largely for Python documentation. I like it, but the Asciidoc markup is much simpler and more uniform than restructuredText, used by Sphinx.
I also find that the Antora toolset is much easier to work with, and more powerful in a number of ways, than Sphinx.
In case you haven’t tried it yet, pandoc’s conversion might be helpful. The output of pandoc docs/execution.html -t asciidoc:
=== Predicates and rules
This is what “hello world” looks like in Dialog:
[cols=",",]
|===
|(program entry point) |
| |Hello, world!
|===
link:[[Copy to clipboard]]
A Dialog program is a list of _rule definitions_, or _rules_ for short.
A rule definition always begins at the very first column of a line, but
it may span several lines. Subsequent lines of code that belong to the
same rule have to be indented by at least one space or tab character.
Hangs on to a lot of cruft you probably don’t want, but may be less tedious than starting from html, and the worst of it looks pretty amenable to search-and-replace.
Cranking along when I get a chance. It takes maybe 15-30 minutes per chapter.
In the past, when I’ve worked on Dialog projects, I often end up with an ever-growing number of tabs open to different pages of the manual. I think the new documentation, with the much improved navigation, will put an end to that.
Antora also supplies a built-in client-side search facility, built right into the page.
