[doc] Operations Guide removal

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
21 messages Options
12
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

[doc] Operations Guide removal

Alexandra Settle-2

Hi operators,

Please be aware that I have proposed the following patch: https://review.openstack.org/#/c/483937/

 

This removes the Operations Guide from the openstack-manuals repo and will no longer be accessible via docs.openstack.org after the patch merges.

The documentation team does not have the resources to move the ops guide to the wiki ourselves. If you are able to work on the migration, please check out the ‘before-migration’ tag in the repo to access the deleted content. [0]

Once the ops guide is migrated to the wiki, we will help you add a redirect so that the old link on docs.openstack.org will allow users to find the content in the new location.

Thanks,

Alex

 

[0] https://github.com/openstack/openstack-manuals/tree/before-migration


_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [doc] Operations Guide removal

Gregory Orange
On 14/07/17 23:48, Alexandra Settle wrote:
> Please be aware that I have proposed the following patch: https://review.openstack.org/#/c/483937/
>
> This removes the Operations Guide from the openstack-manuals repo and will no longer be accessible via docs.openstack.org after the patch merges.

I am unclear on the order of events here. Recently we found some documentation[1] had been removed because it was going to be put up somewhere else, but was not yet available. Is this the case here? Could it instead be put up somewhere else shortly *before* removing it from the repo?

Regards,
Greg.

[1] I do not recall which, but I can find out if desired

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [doc] Operations Guide removal

Andreas Jaeger
On 2017-07-17 04:39, Gregory Orange wrote:

> On 14/07/17 23:48, Alexandra Settle wrote:
>> Please be aware that I have proposed the following patch:
>> https://review.openstack.org/#/c/483937/
>>
>> This removes the Operations Guide from the openstack-manuals repo and
>> will no longer be accessible via docs.openstack.org after the patch
>> merges.
>
> I am unclear on the order of events here. Recently we found some
> documentation[1] had been removed because it was going to be put up
> somewhere else, but was not yet available. Is this the case here? Could
> it instead be put up somewhere else shortly *before* removing it from
> the repo?

The repo was tagged, so that you can always get it - tag is
before-migration,

Andreas
--
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
       HRB 21284 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [doc] Operations Guide removal

Alexandra Settle-2
In reply to this post by Gregory Orange
Hi Greg,

We have been working to fulfil the implementation process that is outlined in the migration spec[0]

I have been emailing the ops list calling for volunteers to help migrate the operations guide over to the OpenStack wiki. I have had a volunteer, but he is currently on vacation. Perhaps this is to what you are referring to?

As Andreas noted, any documentation can always be accessed using the before-migration tag in the openstack-manuals repo.[1]

If perhaps you are referring to another document, it would be helpful if you could find the relevant materials :)

Hopefully this helps,

Alex

[0] http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html 
[1] https://github.com/openstack/openstack-manuals/tree/before-migration 

On 7/17/17, 3:39 AM, "Gregory Orange" <[hidden email]> wrote:

    On 14/07/17 23:48, Alexandra Settle wrote:
    > Please be aware that I have proposed the following patch: https://review.openstack.org/#/c/483937/
    >
    > This removes the Operations Guide from the openstack-manuals repo and will no longer be accessible via docs.openstack.org after the patch merges.
   
    I am unclear on the order of events here. Recently we found some documentation[1] had been removed because it was going to be put up somewhere else, but was not yet available. Is this the case here? Could it instead be put up somewhere else shortly *before* removing it from the repo?
   
    Regards,
    Greg.
   
    [1] I do not recall which, but I can find out if desired
   
    _______________________________________________
    OpenStack-operators mailing list
    [hidden email]
    http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
   

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [doc] Operations Guide removal

Gregory Orange
Hello Alex and Andreas,

On 17/07/17 16:50, Alexandra Settle wrote:
> I have been emailing the ops list calling for volunteers to help migrate the operations guide over to the OpenStack wiki. I have had a volunteer, but he is currently on vacation. Perhaps this is to what you are referring to?
>
> As Andreas noted, any documentation can always be accessed using the before-migration tag in the openstack-manuals repo.

Thank you both for your responses. The way I read this is: The documentation will become unavailable in its current form, accessible only via github.com; the links within those pages to docs.openstack.org will break, and the navigation layout will be absent. While I appreciate that the material will technically still be available, it will be markedly less accessible to someone trawling for information who does not already have a strong knowledge of that documentation.

Greg.

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [doc] Operations Guide removal

Andreas Jaeger
On 2017-07-18 03:20, Gregory Orange wrote:

> Hello Alex and Andreas,
>
> On 17/07/17 16:50, Alexandra Settle wrote:
>> I have been emailing the ops list calling for volunteers to help
>> migrate the operations guide over to the OpenStack wiki. I have had a
>> volunteer, but he is currently on vacation. Perhaps this is to what
>> you are referring to?
>>
>> As Andreas noted, any documentation can always be accessed using the
>> before-migration tag in the openstack-manuals repo.
>
> Thank you both for your responses. The way I read this is: The
> documentation will become unavailable in its current form, accessible
> only via github.com; the links within those pages to docs.openstack.org
> will break, and the navigation layout will be absent. While I appreciate
> that the material will technically still be available, it will be
> markedly less accessible to someone trawling for information who does
> not already have a strong knowledge of that documentation.


Gregory, we discussed this in the past here. The guide is outdated and
orphaned. We asked how to move forward and the feedback by operators
was: We (= some operators) move it to the wiki and maintain it there.

Yes, we're not going to keep an outdated version published as is. This
needs people to drive the guide forward and none have shown up to move
it forward in the existing form,

Andreas
--
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
       HRB 21284 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [doc] Operations Guide removal

Gregory Orange
On 18/07/17 14:18, Andreas Jaeger wrote:
> Gregory, we discussed this in the past here. The guide is outdated and
> orphaned. We asked how to move forward and the feedback by operators
> was: We (= some operators) move it to the wiki and maintain it there.
>
> Yes, we're not going to keep an outdated version published as is. This
> needs people to drive the guide forward and none have shown up to move
> it forward in the existing form,

Please forgive my naivete here - I am quite new to OpenStack and as such to the community. I have found that in this project as well as in others, old documentation can be surprisingly useful, especially when marked with a date or version.

I recognise that volunteer time is limited, and am interested to see how the new ideas for documentation will go. At the same time, significantly reduced access to documentation - yes, even outdated, orphaned documentation - will make life more difficult for this new operator. If the decision is fixed and there is no will to avoid an outage in this manner, then I guess that is about all I can say.

I will say a word of thanks to you and all of the contributors to the documentation so far. It is critical to anyone starting to use such a massive set of software. I hope that the migration to wiki arrangements is smooth and successful.

Regards,
Greg.

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [doc] Operations Guide removal

Alexandra Settle-2

    Please forgive my naivete here - I am quite new to OpenStack and as such to the community. I have found that in this project as well as in others, old documentation
..  can be surprisingly useful, especially when marked with a date or version.

We completely agree with you here, which is why we are attempting to give this document back to the operations community. This does, however, mean a small amount of downtime.
   
    I recognise that volunteer time is limited, and am interested to see how the new ideas for documentation will go. At the same time, significantly reduced access to
    documentation - yes, even outdated, orphaned documentation - will make life more difficult for this new operator. If the decision is fixed and there is no will to avoid
    an outage in this manner, then I guess that is about all I can say.

We also completely agree with you here too. However, one of the many discussions that has continuously come up on ML and during summit and design conference sessions is that our operators find it difficult to contribute to the documentation as is. Our method of treating documentation like code does not suit all, so this is in part an attempt to solve that problem. This does mean that along the way, we are going to have some downtime. But the end goal is to allow our operators to access documentation to be able to update more easily and frequently – hopefully to help future, new, operators like yourself.

The decision has been made, per say. But we hope that this new solution will prove to be fruitful :)
   
    I will say a word of thanks to you and all of the contributors to the documentation so far. It is critical to anyone starting to use such a massive set of software. I hope
    that the migration to wiki arrangements is smooth and successful.

So far, so good! Thanks for your note, Greg :) please reach out with any concerns or questions you may have. I’m on IRC as “asettle” or easily contactable via email if that suits you best :)

    _______________________________________________
    OpenStack-operators mailing list
    [hidden email]
    http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
   

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [OpenStack-docs] [doc] Operations Guide removal

Blair Bethwaite
In reply to this post by Alexandra Settle-2
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)...?

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?

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.

Cheers,

On 15 July 2017 at 01:48, Alexandra Settle <[hidden email]> wrote:

> Hi operators,
>
> Please be aware that I have proposed the following patch:
> https://review.openstack.org/#/c/483937/
>
>
>
> This removes the Operations Guide from the openstack-manuals repo and will
> no longer be accessible via docs.openstack.org after the patch merges.
>
> The documentation team does not have the resources to move the ops guide to
> the wiki ourselves. If you are able to work on the migration, please check
> out the ‘before-migration’ tag in the repo to access the deleted content.
> [0]
>
> Once the ops guide is migrated to the wiki, we will help you add a redirect
> so that the old link on docs.openstack.org will allow users to find the
> content in the new location.
>
> Thanks,
>
> Alex
>
>
>
> [0] https://github.com/openstack/openstack-manuals/tree/before-migration
>
>
> _______________________________________________
> OpenStack-docs mailing list
> [hidden email]
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



--
Cheers,
~Blairo

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [OpenStack-docs] [doc] Operations Guide removal

Alexandra Settle-2
Hey Blair!

Thanks for looking into this… Adding Mario and Erik who both also volunteered their time :)

1. I can say confidently that the content that lives at https://wiki.openstack.org/wiki/Documentation/OpsGuide can be removed. I am happy to do this if you would like to use this URL?
2. We (very successfully) used pandoc during our conversion from XML to RST. I would recommend it. I admit I haven’t tried converting to a mediaWiki format. But hey, worth trying… I guess the other option is manually copying across and editing. (Unless someone has a script lying around?)
3. It’s a good question, one I’m not really sure how to answer. The idea of pushing back to the wiki was so that the operators can own. Having the guide linked from docs.o.o will still ensure there is traffic, and people are able to edit. Perhaps the best idea for this is to use the documentation liaison for Ops as a first point of call? What do you think about that? Currently Robert Starmer is our liaison (https://wiki.openstack.org/wiki/CrossProjectLiaisons#Documentation ) but seeing as we’re now making this more of an official ownership thing, we should be revisiting the responsibilities of the ops docs liaison?

Cheers,

Alex

On 7/19/17, 11:40 AM, "Blair Bethwaite" <[hidden email]> wrote:

    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)...?
   
    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?
   
    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.
   
    Cheers,
   
    On 15 July 2017 at 01:48, Alexandra Settle <[hidden email]> wrote:
    > Hi operators,
    >
    > Please be aware that I have proposed the following patch:
    > https://review.openstack.org/#/c/483937/
    >
    >
    >
    > This removes the Operations Guide from the openstack-manuals repo and will
    > no longer be accessible via docs.openstack.org after the patch merges.
    >
    > The documentation team does not have the resources to move the ops guide to
    > the wiki ourselves. If you are able to work on the migration, please check
    > out the ‘before-migration’ tag in the repo to access the deleted content.
    > [0]
    >
    > Once the ops guide is migrated to the wiki, we will help you add a redirect
    > so that the old link on docs.openstack.org will allow users to find the
    > content in the new location.
    >
    > Thanks,
    >
    > Alex
    >
    >
    >
    > [0] https://github.com/openstack/openstack-manuals/tree/before-migration
    >
    >
    > _______________________________________________
    > OpenStack-docs mailing list
    > [hidden email]
    > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
    >
   
   
   
    --
    Cheers,
    ~Blairo
   

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [OpenStack-docs] [doc] Operations Guide removal

Doug Hellmann-2
In reply to this post by Blair Bethwaite
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. :-)

> 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
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [OpenStack-docs] [doc] Operations Guide removal

Anne Gentle
On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann <[hidden email]> 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, 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 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/
ops-guide/ops-network-troubleshooting.html
Then see how much you get from Pandoc.


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
> [hidden email]
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators



--

Read my blog: justwrite.click
Subscribe to Docs|Code: docslikecode.com

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [OpenStack-docs] [doc] Operations Guide removal

Doug Hellmann-2
Excerpts from Yuki Kasuya's message of 2017-08-10 17:09:48 +0900:

>
> 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@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)

It should be safe to ignore the toctree directives. If you want to keep
the same structure between the wiki pages and the original source
document, you might want to replace those with lists of links.

The term role automatically links to the glossary. As long as the text
highlighted by the role is present in the output, it is fine to ignore
that warning, too.

Doug

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [OpenStack-docs] [doc] Operations Guide removal

Anne Gentle
In reply to this post by Anne Gentle
On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya <[hidden email]> wrote:

> Hi,
>
>
> On 7/19/17 23:51, Anne Gentle wrote:
>>
>> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann <[hidden email]>
>> 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, 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
>> 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/
>> 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@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
2. 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
>>> [hidden email]
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>>
>>
>>
>>
>
> --
> ---------------------------------------------
> KDDI Research, Inc.
> Integrated Core Network Control
> And Management Laboratory
> Yuki Kasuya
> [hidden email]
> +81 80 9048 8405



--

Read my blog: justwrite.click
Subscribe to Docs|Code: docslikecode.com

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [OpenStack-docs] [doc] Operations Guide removal

Chris Morgan
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 <[hidden email]> wrote:
On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya <[hidden email]> wrote:
> Hi,
>
>
> On 7/19/17 23:51, Anne Gentle wrote:
>>
>> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann <[hidden email]>
>> 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, 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
>> 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/
>> 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@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
2. 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
>>> [hidden email]
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>>
>>
>>
>>
>
> --
> ---------------------------------------------
> KDDI Research, Inc.
> Integrated Core Network Control
> And Management Laboratory
> Yuki Kasuya
> [hidden email]
> <a href="tel:%2B81%2080%209048%208405" value="+818090488405">+81 80 9048 8405



--

Read my blog: justwrite.click
Subscribe to Docs|Code: docslikecode.com

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators



--
Chris Morgan <[hidden email]>

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [OpenStack-docs] [doc] Operations Guide removal

Yuki Kasuya
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
> <[hidden email] <mailto:[hidden email]>>
> wrote:
>
>     On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya
>     <[hidden email] <mailto:[hidden email]>> wrote:
>     > Hi,
>     >
>     >
>     > On 7/19/17 23:51, Anne Gentle wrote:
>     >>
>     >> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann
>     <[hidden email] <mailto:[hidden email]>>
>     >> 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@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
>     >>> [hidden email]
>     <mailto:[hidden email]>
>     >>> 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
>     > [hidden email] <mailto:[hidden email]>
>     > +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
>     [hidden email]
>     <mailto:[hidden email]>
>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>     <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators>
>
>
>
>
> --
> Chris Morgan <[hidden email] <mailto:[hidden email]>>
--
---------------------------------------------
KDDI Research, Inc.
Integrated Core Network Control
And Management Laboratory
Yuki Kasuya
[hidden email]
+81 80 9048 8405

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

ops-users.rst.txt (14K) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [OpenStack-docs] [doc] Operations Guide removal

Chris Morgan
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 <[hidden email]> 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
<[hidden email] <mailto:[hidden email]>>
wrote:

    On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya
    <[hidden email] <mailto:[hidden email]>> wrote:
    > Hi,
    >
    >
    > On 7/19/17 23:51, Anne Gentle wrote:
    >>
    >> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann
    <[hidden email] <mailto:[hidden email]>>
    >> 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@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
    >>> [hidden email]
    <mailto:[hidden email]>
    >>> 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
    > [hidden email] <mailto:[hidden email]>
    > <a href="tel:%2B81%2080%209048%208405" value="+818090488405" target="_blank">+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
    [hidden email]
    <mailto:[hidden email]>
    http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
    <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators>




--
Chris Morgan <[hidden email] <mailto:[hidden email]>>

--
---------------------------------------------
KDDI Research, Inc.
Integrated Core Network Control
And Management Laboratory
Yuki Kasuya
[hidden email]
<a href="tel:%2B81%2080%209048%208405" value="+818090488405" target="_blank">+81 80 9048 8405



--
Chris Morgan <[hidden email]>

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [OpenStack-docs] [doc] Operations Guide removal

Chris Morgan
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 <[hidden email]> 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 <[hidden email]
>> <mailto:[hidden email]>> 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
>>        <[hidden email]
>>        <mailto:[hidden email]>
>>        <mailto:[hidden email]
>>        <mailto:[hidden email]>>>
>>        wrote:
>>
>>            On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya
>>            <[hidden email]
>>        <mailto:[hidden email]>
>>        <mailto:[hidden email]
>>        <mailto:[hidden email]>>> wrote:
>>            > Hi,
>>            >
>>            >
>>            > On 7/19/17 23:51, Anne Gentle wrote:
>>            >>
>>            >> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann
>>            <[hidden email] <mailto:[hidden email]>
>>        <mailto:[hidden email] <mailto:[hidden email]>>>
>>            >> 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@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
>>            >>> [hidden email]
>>        <mailto:[hidden email]>
>>            <mailto:[hidden email]
>>        <mailto:[hidden email]>>
>>            >>>
>>        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
>>            > [hidden email] <mailto:[hidden email]>
>>        <mailto:[hidden email] <mailto:[hidden email]>>
>>            > +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
>>            [hidden email]
>>        <mailto:[hidden email]>
>>            <mailto:[hidden email]
>>        <mailto:[hidden email]>>
>>
>>        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 <[hidden email] <mailto:[hidden email]>
>>        <mailto:[hidden email] <mailto:[hidden email]>>>
>>
>>
>>    --
>>    ---------------------------------------------
>>    KDDI Research, Inc.
>>    Integrated Core Network Control
>>    And Management Laboratory
>>    Yuki Kasuya
>>    [hidden email] <mailto:[hidden email]>
>>    +81 80 9048 8405 <tel:%2B81%2080%209048%208405>
>>
>>
>>
>>
>> --
>> Chris Morgan <[hidden email] <mailto:[hidden email]>>
>
> --
> ---------------------------------------------
> KDDI Research, Inc.
> Integrated Core Network Control
> And Management Laboratory
> Yuki Kasuya
> [hidden email]
> +81 80 9048 8405
> <mediawiki.tar>

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [OpenStack-docs] [doc] Operations Guide removal

Chris Morgan
In reply to this post by Chris Morgan
I have just completed loading the files into the wiki for perusal. You can see the files here in my contrib list

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 <[hidden email]> 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 <[hidden email]
<mailto:[hidden email]>> 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
        <[hidden email]
        <mailto:[hidden email]>
        <mailto:[hidden email]
        <mailto:[hidden email]>>>
        wrote:

            On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya
            <[hidden email]
        <mailto:[hidden email]>
        <mailto:[hidden email]
        <mailto:[hidden email]>>> wrote:
            > Hi,
            >
            >
            > On 7/19/17 23:51, Anne Gentle wrote:
            >>
            >> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann
            <[hidden email] <mailto:[hidden email]>
        <mailto:[hidden email] <mailto:[hidden email]>>>

            >> 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@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
            >>> [hidden email]
        <mailto:[hidden email]>
            <mailto:[hidden email]
        <mailto:[hidden email]>>
            >>>
        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
            > [hidden email] <mailto:[hidden email]>
        <mailto:[hidden email] <mailto:[hidden email]>>
            > <a href="tel:%2B81%2080%209048%208405" value="+818090488405" target="_blank">+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
            [hidden email]
        <mailto:[hidden email]>
            <mailto:[hidden email]
        <mailto:[hidden email]>>

        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 <[hidden email] <mailto:[hidden email]>
        <mailto:[hidden email] <mailto:[hidden email]>>>


    --
    ---------------------------------------------
    KDDI Research, Inc.
    Integrated Core Network Control
    And Management Laboratory
    Yuki Kasuya
    [hidden email] <mailto:[hidden email]>
    <a href="tel:%2B81%2080%209048%208405" value="+818090488405" target="_blank">+81 80 9048 8405 <tel:%2B81%2080%209048%208405>




--
Chris Morgan <[hidden email] <mailto:[hidden email]>>

--
---------------------------------------------
KDDI Research, Inc.
Integrated Core Network Control
And Management Laboratory
Yuki Kasuya
[hidden email]
<a href="tel:%2B81%2080%209048%208405" value="+818090488405" target="_blank">+81 80 9048 8405



--
Chris Morgan <[hidden email]>

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [OpenStack-docs] [doc] Operations Guide removal

Yuki Kasuya
Hi Chris,

Thank you for creating lots of wiki pages! I'll check of them.

Best regards,
Yuki

On 8/19/17 06:04, Chris Morgan wrote:

> 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 <[hidden email]
> <mailto:[hidden email]>> 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>
>         <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
>         <[hidden email] <mailto:[hidden email]>
>         <mailto:[hidden email]
>         <mailto:[hidden email]>>> 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>
>             <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/acknowledgements
>         <https://wiki.openstack.org/wiki/OpsGuide/acknowledgements>>
>             https://wiki.openstack.org/wiki/OpsGuide/app-crypt
>         <https://wiki.openstack.org/wiki/OpsGuide/app-crypt>
>             <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
>                 <[hidden email]
>         <mailto:[hidden email]>
>                 <mailto:[hidden email]
>         <mailto:[hidden email]>>
>                 <mailto:[hidden email]
>         <mailto:[hidden email]>
>                 <mailto:[hidden email]
>         <mailto:[hidden email]>>>>
>                 wrote:
>
>                     On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya
>                     <[hidden email]
>         <mailto:[hidden email]>
>                 <mailto:[hidden email]
>         <mailto:[hidden email]>>
>                 <mailto:[hidden email]
>         <mailto:[hidden email]>
>                 <mailto:[hidden email]
>         <mailto:[hidden email]>>>> wrote:
>                     > Hi,
>                     >
>                     >
>                     > On 7/19/17 23:51, Anne Gentle wrote:
>                     >>
>                     >> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann
>                     <[hidden email]
>         <mailto:[hidden email]> <mailto:[hidden email]
>         <mailto:[hidden email]>>
>                 <mailto:[hidden email]
>         <mailto:[hidden email]> <mailto:[hidden email]
>         <mailto:[hidden email]>>>>
>
>                     >> 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>>
>
>         <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>>
>                     <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/>
>                 <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@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>>
>
>         <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>>
>
>         <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
>                     >>> [hidden email]
>         <mailto:[hidden email]>
>                 <mailto:[hidden email]
>         <mailto:[hidden email]>>
>                     <mailto:[hidden email]
>         <mailto:[hidden email]>
>                 <mailto:[hidden email]
>         <mailto:[hidden email]>>>
>                     >>>
>
>         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>>
>
>
>         <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
>                     > [hidden email]
>         <mailto:[hidden email]> <mailto:[hidden email]
>         <mailto:[hidden email]>>
>                 <mailto:[hidden email]
>         <mailto:[hidden email]> <mailto:[hidden email]
>         <mailto:[hidden email]>>>
>                     > +81 80 9048 8405 <tel:%2B81%2080%209048%208405>
>         <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> <http://docslikecode.com>
>
>                     _______________________________________________
>                     OpenStack-operators mailing list
>                     [hidden email]
>         <mailto:[hidden email]>
>                 <mailto:[hidden email]
>         <mailto:[hidden email]>>
>                     <mailto:[hidden email]
>         <mailto:[hidden email]>
>                 <mailto:[hidden email]
>         <mailto:[hidden email]>>>
>
>
>         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>>
>
>
>         <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 <[hidden email]
>         <mailto:[hidden email]> <mailto:[hidden email]
>         <mailto:[hidden email]>>
>                 <mailto:[hidden email] <mailto:[hidden email]>
>         <mailto:[hidden email] <mailto:[hidden email]>>>>
>
>
>             --
>             ---------------------------------------------
>             KDDI Research, Inc.
>             Integrated Core Network Control
>             And Management Laboratory
>             Yuki Kasuya
>             [hidden email] <mailto:[hidden email]>
>         <mailto:[hidden email] <mailto:[hidden email]>>
>             +81 80 9048 8405 <tel:%2B81%2080%209048%208405>
>         <tel:%2B81%2080%209048%208405>
>
>
>
>
>         --
>         Chris Morgan <[hidden email] <mailto:[hidden email]>
>         <mailto:[hidden email] <mailto:[hidden email]>>>
>
>
>     --
>     ---------------------------------------------
>     KDDI Research, Inc.
>     Integrated Core Network Control
>     And Management Laboratory
>     Yuki Kasuya
>     [hidden email] <mailto:[hidden email]>
>     +81 80 9048 8405 <tel:%2B81%2080%209048%208405>
>
>
>
>
> --
> Chris Morgan <[hidden email] <mailto:[hidden email]>>

--
---------------------------------------------
KDDI Research, Inc.
Integrated Core Network Control
And Management Laboratory
Yuki Kasuya
[hidden email]
+81 80 9048 8405

_______________________________________________
OpenStack-operators mailing list
[hidden email]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
12
Loading...