[release] considering documentation migration to ReStructuredText/Sphinx from AsciiDoc/Asciidoctor

Gao Kai <gaok12@...>

Jensen, Xiao and other folks,

Please see the e-mail and prepare for migrations ahead of time.


-------- Forwarded Message --------
Subject: Re: [release] considering documentation migration to ReStructuredText/Sphinx from AsciiDoc/Asciidoctor
Date: Thu, 7 Jul 2016 11:32:11 -0400
From: Alexis de Talhouët <adetalhouet@...>
To: Colin Dixon <colin@...>
CC: release@... <release@...>, ODL Docs <documentation@...>

Awesome, great look and feel! Thanks Colin, Thanh and all the others involved in this migration.


On Jul 7, 2016, at 9:38 AM, Colin Dixon <colin@...> wrote:

For what it's worth, thanks to Thanh, we've been able to get the migrated documentation showing up here:


On Thu, Jun 23, 2016 at 12:05 PM, Colin Dixon <colin@...> wrote:
I think many of you may have heard that the documentation team has been experimenting with migrating toolchains to address complaints people have had—especially that we don't produce good HTML-formatted documentation.

For that and a few other reasons, we've been looking into moving from the current system we used with a custom maven plugin that then invokes Asciidoctor [0] to build AsciiDoc in favor of using Sphinx [2] to build ReStructuredText [3], which is the standard adopted for the documentation of most Python projects.

As a proof-of-concept, we've migrated the Beryllium-revised getting started guide [4], OpenDaylight and OpenStack guide [5] and infrastructure guide [6] into the new toolchain [7] and gotten it so it publishes automatically on every merge to read the docs [8]. There are outstanding patches [9] to migrate the older Getting Started Guide content into this toolchain as well.

The new toolchain also offers nice features like the ability to automatically allow people to switch between different versions of the documentation for different releases, automatically provide warnings when looking at documentation corresponding to outdated release and the like.

Also, the infrastructure guide [6] is already a working example of including documentation from another project thus allowing for projects to host their own documentation files in their repository if they would like.

With this experience, we're hoping to write some short tutorials about migrating documentation from AsciiDoc to ReStructuredText (it's been pretty easy) and talk about maybe migrating the bulk of the documentation as part of the Carbon release unless there's such overwhelming support that we feel like we should push to migrate everything in Boron.

release mailing list