[Openstack-operators] [OpenStack-docs] [doc] Operations Guide removal
annegentle at justwriteclick.com
Thu Aug 10 12:47:04 UTC 2017
On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya <yu-kasuya at kddi-research.jp> wrote:
> On 7/19/17 23:51, Anne Gentle wrote:
>> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann <doug at doughellmann.com>
>>> 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
>> Here's what I was thinking:
>> If you're interested in the export, run an experiment with Pandoc to
>> convert from RST to Mediawiki.
>> You'll likely still have cleanup but it's a start. Only convert
>> troubleshooting to start, which gets the most hits: docs.openstack.org/
>> 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
> 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:  is for glossary entries,
and a toctree directive  is for a table of contents insertion.
Thanks for testing the theory and making it practical.
>> Hope this helps -
>>>> 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?
>>> OpenStack-operators mailing list
>>> OpenStack-operators at lists.openstack.org
> 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
More information about the OpenStack-operators