devportal VS antora

Hello folks, I am running a tech writing team (along with product management). I am not expert in documentation platforms. Today we have a challenging custom-built documentation platform based on Sphinx and a bunch of cobbled together technologies aiven/devportal: Resources for users of the projects on the Aiven platform (github.com) . Our documentation is in .rst markup language due to the Python focus.

Humble brag that the last one in the list (Aiven 🦀) won 2022 DevPortal Awards in the category Best DevPortal Beyond REST Platforms. If I added a list of great docs websites but didn't include the OG, it would be a crime. Check out one of THE BEST documentation out there - Stripe Docs, built using Markdoc.

You can find a list of Aiven's cloud providers on [Developer.aiven.io], which is also the portal where we host the developer documentation. To quickly retrieve a list of currently-available cloud providers, my colleague Lorna Mitchell wrote a Python script that pulls our cloud listing from the Aiven API and generates documentation, which is really cool!

Unlike docToolchain or Asciidoctor, Antora is a true framework for Asciidoc that can store, retrieve, and aggregate all Asciidoc content from multiple git repositories. Antora’s page referencing system isn’t coupled to filesystem paths or URLs. You are able to cross reference pages across a local machine, a staging environment, and a production environment. To generate a site with Antora, you need the Antora CLI and Antora site generator.