<div dir="ltr">I just got back from the ops meetup in Mexico City and I think I volunteered to help with this ops guide transition and maintaining it on the wiki. So if the current output of the conversion is available anywhere for review I could try being a proofreader for it. It seems there is approval to put it as is on the wiki, what does that require?<div><br></div><div>I am not very familiar with the docs build process so if we are still attempting to get a minimally viable conversion I may be able to help but will need more time to come up to speed with that.</div><div><br></div><div>Chris</div></div><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Aug 10, 2017 at 8:47 AM, Anne Gentle <span dir="ltr"><<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya <<a href="mailto:yu-kasuya@kddi-research.jp">yu-kasuya@kddi-research.jp</a>> wrote:<br>
> Hi,<br>
<div><div class="h5">><br>
><br>
> On 7/19/17 23:51, Anne Gentle wrote:<br>
>><br>
>> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann <<a href="mailto:doug@doughellmann.com">doug@doughellmann.com</a>><br>
>> wrote:<br>
>>><br>
>>> Excerpts from Blair Bethwaite's message of 2017-07-19 20:40:25 +1000:<br>
>>>><br>
>>>> Hi Alex,<br>
>>>><br>
>>>> I just managed to take a half hour to look at this and have a few<br>
>>>> questions/comments towards making a plan for how to proceed with<br>
>>>> moving the Ops Guide content to the wiki...<br>
>>>><br>
>>>> 1) Need to define wiki location and structure. Curiously at the moment<br>
>>>> there is already meta content at<br>
>>>> <a href="https://wiki.openstack.org/wiki/Documentation/OpsGuide" rel="noreferrer" target="_blank">https://wiki.openstack.org/<wbr>wiki/Documentation/OpsGuide</a>, Maybe the<br>
>>>> content could live at <a href="https://wiki.openstack.org/wiki/OpsGuide" rel="noreferrer" target="_blank">https://wiki.openstack.org/<wbr>wiki/OpsGuide</a>? I<br>
>>>> think it makes sense to follow the existing structure with possible<br>
>>>> exception of culling wrong / very-out-of-date content (but perhaps<br>
>>>> anything like that should be done as a later step and keep it simple<br>
>>>> aiming for a "like-for-like" migration to start with)...?<br>
>>><br>
>>><br>
>>> Yes, I would recommend moving the existing content and then making any<br>
>>> major changes to it.<br>
>>><br>
>>>> 2) Getting the content into the wiki. Looks like there is no obvious<br>
>>>> up-to-date RST import functionality for MediaWiki. Pandoc seems as<br>
>>>> though it might support some useful conversions but I didn't try this<br>
>>>> yet and don't have any experience with it - can anyone say with<br>
>>>> authority whether it is worth pursuing?<br>
>>><br>
>>><br>
>>> I can't say with authority myself, but I can refer to Anne as an<br>
>>> authority. :-)<br>
>><br>
>><br>
>> Ha, well, I think Pandoc is the one to try first, let's say that for<br>
>> starters.<br>
>><br>
>> Here's what I was thinking:<br>
>> If you're interested in the export, run an experiment with Pandoc to<br>
>> convert from RST to Mediawiki.<br>
>><br>
>> <a href="http://pandoc.org/demos.html" rel="noreferrer" target="_blank">http://pandoc.org/demos.html</a><br>
>><br>
>> You'll likely still have cleanup but it's a start. Only convert<br>
>> troubleshooting to start, which gets the most hits: <a href="http://docs.openstack.org/" rel="noreferrer" target="_blank">docs.openstack.org/</a><br>
>> ops-guide/ops-network-<wbr>troubleshooting.html<br>
>> Then see how much you get from Pandoc.<br>
>><br>
><br>
</div></div><span class="">> I tried to convert all docs under ops-guide dir using pandoc. Like below,<br>
> toctree,term and some directives doesn't work after converting. But, at<br>
> glance, almost fine after converting.<br>
> If you don't mind, I'll able to create wiki pages of ops-guide.<br>
><br>
> xxx@devstack02:~/work/<wbr>openstack-manuals/doc/ops-<wbr>guide/source$ pandoc<br>
> index.rst -t mediawiki -o index<br>
> .wiki<br>
> pandoc: ignoring unknown directive: toctree "source" (line 58, column 1)<br>
> pandoc: ignoring unknown role :term: in "source" (line 20, column 13)<br>
> pandoc: ignoring unknown role :term: in "source" (line 19, column 59)<br>
><br>
<br>
</span>Fantastic! That's better that I thought it would do, I'll admit. :)<br>
You may have figured this out, but :term: [1] is for glossary entries,<br>
and a toctree directive [2] is for a table of contents insertion.<br>
<br>
Thanks for testing the theory and making it practical.<br>
<br>
Anne<br>
<br>
1. <a href="http://www.sphinx-doc.org/en/stable/markup/inline.html" rel="noreferrer" target="_blank">http://www.sphinx-doc.org/en/<wbr>stable/markup/inline.html</a><br>
2. <a href="http://www.sphinx-doc.org/en/stable/markup/toctree.html" rel="noreferrer" target="_blank">http://www.sphinx-doc.org/en/<wbr>stable/markup/toctree.html</a><br>
<span class=""><br>
<br>
<br>
>><br>
>> Hope this helps -<br>
>> Anne<br>
>><br>
>>><br>
>>>> 3) Future management - obvious can of worms given this is much better<br>
>>>> addressed by all the tooling and scaffolding the docs team already<br>
>>>> provides around the repos... but nonetheless some expectations may<br>
>>>> need to be set upfront to avoid future pain.<br>
>>><br>
>>><br>
>>> What sort of issues do you foresee?<br>
>>><br>
>>> Doug<br>
>>><br>
>>> ______________________________<wbr>_________________<br>
>>> OpenStack-operators mailing list<br>
>>> <a href="mailto:OpenStack-operators@lists.openstack.org">OpenStack-operators@lists.<wbr>openstack.org</a><br>
>>> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-operators</a><br>
>><br>
>><br>
>><br>
>><br>
><br>
> --<br>
</span>> ------------------------------<wbr>---------------<br>
> KDDI Research, Inc.<br>
> Integrated Core Network Control<br>
> And Management Laboratory<br>
> Yuki Kasuya<br>
> <a href="mailto:yu-kasuya@kddilabs.jp">yu-kasuya@kddilabs.jp</a><br>
> <a href="tel:%2B81%2080%209048%208405" value="+818090488405">+81 80 9048 8405</a><br>
<div class="HOEnZb"><div class="h5"><br>
<br>
<br>
--<br>
<br>
Read my blog: justwrite.click<br>
Subscribe to Docs|Code: <a href="http://docslikecode.com" rel="noreferrer" target="_blank">docslikecode.com</a><br>
<br>
______________________________<wbr>_________________<br>
OpenStack-operators mailing list<br>
<a href="mailto:OpenStack-operators@lists.openstack.org">OpenStack-operators@lists.<wbr>openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-operators</a><br>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature" data-smartmail="gmail_signature">Chris Morgan <<a href="mailto:mihalis68@gmail.com" target="_blank">mihalis68@gmail.com</a>></div>
</div>