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

Colin Dixon colin at colindixon.com
Fri Jul 8 14:46:58 UTC 2016


It might be useful to look at this:
http://docs.opendaylight.org/en/latest/documentation.html

Though I'm still improving it and feel free to contribute changes. The
source file for it is here:
https://github.com/opendaylight/docs/blob/master/docs/documentation.rst

--Colin


On Fri, Jul 8, 2016 at 2:35 AM, Anil Vishnoi <vishnoianil at gmail.com> wrote:

> Sometime next week, i am planning to spend some time on the documentation
> of OVSDB project, so I am looking forward to the tutorial you/thanh is
> planning to write. Meanwhile i will look at the integration project doc
> stuff as well and above link you pasted to give it a first shot.
>
> On Thu, Jul 7, 2016 at 11:56 AM, Colin Dixon <colin at colindixon.com> wrote:
>
>> Also, even the Linux Kernel seems to be moving to using Sphinx for its
>> docs:
>> https://lwn.net/SubscriberLink/692704/76b77c4eaa4a409a/
>>
>> Thanks to Andy and Thanh for pointing it out.
>>
>> --Colin
>>
>>
>> On Thu, Jul 7, 2016 at 9:38 AM, Colin Dixon <colin at colindixon.com> 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 at colindixon.com>
>>> 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 at lists.opendaylight.org
>> https://lists.opendaylight.org/mailman/listinfo/release
>>
>>
>
>
> --
> Thanks
> Anil
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.opendaylight.org/pipermail/release/attachments/20160708/78b2c28f/attachment.html>


More information about the release mailing list