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

Chris Morgan mihalis68 at gmail.com
Tue Aug 15 01:54:09 UTC 2017


I'll get these loaded and see how they look, thanks!

Chris

Sent from my iPhone

> On 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-guide/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/openstack-operators
>>        <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators>
>> 
>>        <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>>        <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 <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/openstack-operators
>>        <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators>
>> 
>>        <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>>        <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-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
> <mediawiki.tar>



More information about the OpenStack-operators mailing list