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

Chris Morgan mihalis68 at gmail.com
Fri Aug 18 21:04:02 UTC 2017


I have just completed loading the files into the wiki for perusal. You can
see the files here in my contrib list
https://wiki.openstack.org/wiki/Special:Contributions/Cmorgan2

I have not fixed the contents page (which was blank) nor made forward and
back links so that you can go from one to the next page. This just allows
us to see how the conversion output looks right now. I am aware we may need
to redo all this. Please take a look!

Chris

On Mon, Aug 14, 2017 at 9:07 PM, Yuki Kasuya <yu-kasuya at kddi-research.jp>
wrote:

> Hi Chris,
>
> Attached is all converting files under "openstack-manuals/doc/ops-gui
> de/source".
>
> Best regards,
> Yuki
>
> On 8/15/17 03:15, Chris Morgan wrote:
>
>> I have privileges to edit wiki pages on openstack.org
>> <http://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
>> <mailto: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
>>     <https://wiki.openstack.org/wiki/OpsGuide> (as index)
>>     https://wiki.openstack.org/wiki/OpsGuide/acknowledgements
>>     <https://wiki.openstack.org/wiki/OpsGuide/acknowledgements>
>>     https://wiki.openstack.org/wiki/OpsGuide/app-crypt
>>     <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>
>>         <mailto: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>
>>         <mailto: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>
>>         <mailto: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>
>>             <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>
>>             <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/>
>>         <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>
>>             <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>
>>             <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>
>>             <mailto: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>
>>
>>         <http://lists.openstack.org/cgi-bin/mailman/listinfo/opensta
>> ck-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>
>>         <mailto:yu-kasuya at kddilabs.jp <mailto:yu-kasuya at kddilabs.jp>>
>>             > +81 80 9048 8405 <tel:%2B81%2080%209048%208405>
>>         <tel:%2B81%2080%209048%208405>
>>
>>
>>
>>             --
>>
>>             Read my blog: justwrite.click
>>             Subscribe to Docs|Code: docslikecode.com
>>         <http://docslikecode.com> <http://docslikecode.com>
>>
>>             _______________________________________________
>>             OpenStack-operators mailing list
>>             OpenStack-operators at lists.openstack.org
>>         <mailto:OpenStack-operators at lists.openstack.org>
>>             <mailto: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>
>>
>>         <http://lists.openstack.org/cgi-bin/mailman/listinfo/opensta
>> ck-operators
>>         <http://lists.openstack.org/cgi-bin/mailman/listinfo/opensta
>> ck-operators>>
>>
>>
>>
>>
>>         --
>>         Chris Morgan <mihalis68 at gmail.com <mailto:mihalis68 at gmail.com>
>>         <mailto: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 <mailto:yu-kasuya at kddilabs.jp>
>>     +81 80 9048 8405 <tel:%2B81%2080%209048%208405>
>>
>>
>>
>>
>> --
>> 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/20170818/a62d2de7/attachment.html>


More information about the OpenStack-operators mailing list