[Openstack-operators] [OpenStack-docs] [doc] Operations Guide removal

Chris Morgan mihalis68 at gmail.com
Mon Aug 14 18:15:00 UTC 2017


I have privileges to edit wiki pages on openstack.org so you could send me
a few converted pages (perhaps ones that link to each other) and I could
upload them and we can all look at the result and see if we like it. Happy
to do that.

Chris

On Sun, Aug 13, 2017 at 9:44 PM, Yuki Kasuya <yu-kasuya at kddi-research.jp>
wrote:

> Hi,
>
> How about that if some directives can be ignored (using pandoc), I'll
> create one new ops-guide page as a example on wiki. After that could you
> review it ? I don't know any approval to create/edit pages on wiki. Or I
> can send you converting files. Attached is a converting example.
> And let's discuss which url is good for new ops-guides like below. Which
> is good using file name or first header as url of wiki? And which directory
> is fine?
>
> https://wiki.openstack.org/wiki/OpsGuide (as index)
> https://wiki.openstack.org/wiki/OpsGuide/acknowledgements
> https://wiki.openstack.org/wiki/OpsGuide/app-crypt
> ...
>
> Best regards,
> Yuki
>
> On 8/12/17 23:38, Chris Morgan wrote:
>
>> 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?
>>
>> 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.
>>
>> Chris
>>
>> On Thu, Aug 10, 2017 at 8:47 AM, Anne Gentle
>> <annegentle at justwriteclick.com <mailto:annegentle at justwriteclick.com>>
>> wrote:
>>
>>     On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya
>>     <yu-kasuya at kddi-research.jp <mailto: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 <mailto: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
>>     <https://wiki.openstack.org/wiki/Documentation/OpsGuide>, Maybe the
>>     >>>> content could live at https://wiki.openstack.org/wiki/OpsGuide
>>     <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/ <http://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
>>     <http://www.sphinx-doc.org/en/stable/markup/inline.html>
>>     2. http://www.sphinx-doc.org/en/stable/markup/toctree.html
>>     <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
>>     <mailto:OpenStack-operators at lists.openstack.org>
>>     >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstac
>> k-operators
>>     <http://lists.openstack.org/cgi-bin/mailman/listinfo/opensta
>> ck-operators>
>>     >>
>>     >>
>>     >>
>>     >>
>>     >
>>     > --
>>     > ---------------------------------------------
>>     > KDDI Research, Inc.
>>     > Integrated Core Network Control
>>     > And Management Laboratory
>>     > Yuki Kasuya
>>     > yu-kasuya at kddilabs.jp <mailto:yu-kasuya at kddilabs.jp>
>>     > +81 80 9048 8405 <tel:%2B81%2080%209048%208405>
>>
>>
>>
>>     --
>>
>>     Read my blog: justwrite.click
>>     Subscribe to Docs|Code: docslikecode.com <http://docslikecode.com>
>>
>>     _______________________________________________
>>     OpenStack-operators mailing list
>>     OpenStack-operators at lists.openstack.org
>>     <mailto:OpenStack-operators at lists.openstack.org>
>>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstac
>> k-operators
>>     <http://lists.openstack.org/cgi-bin/mailman/listinfo/opensta
>> ck-operators>
>>
>>
>>
>>
>> --
>> Chris Morgan <mihalis68 at gmail.com <mailto:mihalis68 at gmail.com>>
>>
>
> --
> ---------------------------------------------
> KDDI Research, Inc.
> Integrated Core Network Control
> And Management Laboratory
> Yuki Kasuya
> yu-kasuya at kddilabs.jp
> +81 80 9048 8405
>



-- 
Chris Morgan <mihalis68 at gmail.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-operators/attachments/20170814/f6fe7fc8/attachment.html>


More information about the OpenStack-operators mailing list