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:
http://docs.opendaylight.org/

--Colin

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.

--Colin

[0] http://asciidoctor.org/
[1] http://www.methods.co.nz/asciidoc/
[2] http://www.sphinx-doc.org/en/stable/
[3] http://docutils.sourceforge.net/rst.html
[4] https://www.opendaylight.org/introduction-getting-started-guide
[5] https://drive.google.com/file/d/0B_rLr6so6DZ8bHdtQkk0Rkk2Wms/view?usp=sharing

[6] https://opendaylight.readthedocs.io/en/latest/submodules/releng/builder/docs/jenkins.html

[7] https://github.com/opendaylight/docs/tree/master/docs
[8] https://opendaylight.readthedocs.io/en/latest/
[9] https://git.opendaylight.org/gerrit/#/q/topic:gsg2rst

_______________________________________________
release mailing list
release@...
https://lists.opendaylight.org/mailman/listinfo/release