Open Stack

On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya <yu-kasuya at kddi-research.jp> wrote:
> Hi,
>
>
> On 7/19/17 23:51, Anne Gentle wrote:
>>
>> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann <doug at doughellmann.com>
>> wrote:
>>>
>>> Excerpts from Blair Bethwaite's message of 2017-07-19 20:40:25 +1000:
>>>>
>>>> Hi Alex,
>>>>
>>>> I just managed to take a half hour to look at this and have a few
>>>> questions/comments towards making a plan for how to proceed with
>>>> moving the Ops Guide content to the wiki...
>>>>
>>>> 1) Need to define wiki location and structure. Curiously at the moment
>>>> there is already meta content at
>>>> https://wiki.openstack.org/wiki/Documentation/OpsGuide, Maybe the
>>>> content could live at https://wiki.openstack.org/wiki/OpsGuide? I
>>>> think it makes sense to follow the existing structure with possible
>>>> exception of culling wrong / very-out-of-date content (but perhaps
>>>> anything like that should be done as a later step and keep it simple
>>>> aiming for a "like-for-like" migration to start with)...?
>>>
>>>
>>> Yes, I would recommend moving the existing content and then making any
>>> major changes to it.
>>>
>>>> 2) Getting the content into the wiki. Looks like there is no obvious
>>>> up-to-date RST import functionality for MediaWiki. Pandoc seems as
>>>> though it might support some useful conversions but I didn't try this
>>>> yet and don't have any experience with it - can anyone say with
>>>> authority whether it is worth pursuing?
>>>
>>>
>>> I can't say with authority myself, but I can refer to Anne as an
>>> authority. :-)
>>
>>
>> Ha, well, I think Pandoc is the one to try first, let's say that for
>> starters.
>>
>> Here's what I was thinking:
>> If you're interested in the export, run an experiment with Pandoc to
>> convert from RST to Mediawiki.
>>
>> http://pandoc.org/demos.html
>>
>> You'll likely still have cleanup but it's a start. Only convert
>> troubleshooting to start, which gets the most hits: docs.openstack.org/
>> ops-guide/ops-network-troubleshooting.html
>> Then see how much you get from Pandoc.
>>
>
> I tried to convert all docs under ops-guide dir using pandoc. Like below,
> toctree,term and some directives doesn't work after converting. But, at
> glance, almost fine after converting.
> If you don't mind, I'll able to create wiki pages of ops-guide.
>
> xxx at devstack02:~/work/openstack-manuals/doc/ops-guide/source$ pandoc
> index.rst -t mediawiki -o index
> .wiki
> pandoc: ignoring unknown directive: toctree "source" (line 58, column 1)
> pandoc: ignoring unknown role :term: in "source" (line 20, column 13)
> pandoc: ignoring unknown role :term: in "source" (line 19, column 59)
>

Fantastic! That's better that I thought it would do, I'll admit. :)
You may have figured this out, but :term: [1] is for glossary entries,
and a toctree directive [2] is for a table of contents insertion.

Thanks for testing the theory and making it practical.

Anne

1. http://www.sphinx-doc.org/en/stable/markup/inline.html
2. http://www.sphinx-doc.org/en/stable/markup/toctree.html



>>
>> Hope this helps -
>> Anne
>>
>>>
>>>> 3) Future management - obvious can of worms given this is much better
>>>> addressed by all the tooling and scaffolding the docs team already
>>>> provides around the repos... but nonetheless some expectations may
>>>> need to be set upfront to avoid future pain.
>>>
>>>
>>> What sort of issues do you foresee?
>>>
>>> Doug
>>>
>>> _______________________________________________
>>> OpenStack-operators mailing list
>>> OpenStack-operators at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>>
>>
>>
>>
>
> --
> ---------------------------------------------
> KDDI Research, Inc.
> Integrated Core Network Control
> And Management Laboratory
> Yuki Kasuya
> yu-kasuya at kddilabs.jp
> +81 80 9048 8405



-- 

Read my blog: justwrite.click
Subscribe to Docs|Code: docslikecode.com