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

[Doug Hellmann]

Excerpts from Chris Morgan's message of 2017-08-18 17:04:02 -0400:
> 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

That looks like a great start. There are some formatting things to
clean up ("note" directives) and some linking where the toctrees
weren't handled (as you point out), but the majority of the content
I skimmed looks good.

Doug

___
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

Re: [Openstack-operators] [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 > 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

 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

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

>


>

 Hi,
>
>
> On 7/19/17 23:51, Anne Gentle wrote:
>>
>> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann
 

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

[Chris Morgan]

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 
wrote:

> Hi Chris,
>
> Attached is all converting files under "openstack-manuals/doc/ops-gui
> de/source".
>
> Best regards,
> Yuki
>
> On 8/15/17 03:15, Chris Morgan wrote:
>
>> I have privileges to edit wiki pages on openstack.org
>>  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 > > 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
>> > 
>> > >>
>> wrote:
>>
>> On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya
>> > 
>> > >> wrote:
>> > Hi,
>> >
>> >
>> > On 7/19/17 23:51, Anne Gentle wrote:
>> >>
>> >> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann
>> 
>> >>
>>
>> >> 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
>>  

Re: [Openstack-operators] [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  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
>>  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 > > 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
>>>
>>>>>
>>wrote:
>> 
>>On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya
>>>
>>>>> wrote:
>>> Hi,
>>>
>>>
>>> On 7/19/17 23:51, Anne Gentle wrote:
>>>>
>>>> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann
>>
>>>>
>>>> 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.

Re: [Openstack-operators] [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 
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
>> >
>> wrote:
>>
>> On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya
>> >
>> wrote:
>> > Hi,
>> >
>> >
>> > On 7/19/17 23:51, Anne Gentle wrote:
>> >>
>> >> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann
>> >
>> >> 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 

Re: [Openstack-operators] [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
>
wrote:

On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya
> wrote:
> Hi,
>
>
> On 7/19/17 23:51, Anne Gentle wrote:
>>
>> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann
>
>> 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. 

Re: [Openstack-operators] [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 
wrote:

> On Thu, Aug 10, 2017 at 3:09 AM, Yuki Kasuya 
> wrote:
> > Hi,
> >
> >
> > On 7/19/17 23:51, Anne Gentle wrote:
> >>
> >> On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann 
> >> 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
> >>> OpenStack-operators@lists.openstack.org
> >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/
> openstack-operators
> >>
> >>
> >>
> >>
> >
> > --
> > -
> > KDDI Research, Inc.
> > Integrated Core Network Control
> > And Management Laboratory
> > Yuki Kasuya
> > yu-kas...@kddilabs.jp
> > +81 80 9048 8405
>
>
>
> --
>
> Read my blog: justwrite.click
> Subscribe to Docs|Code: docslikecode.com
>
> ___
> OpenStack-operators mailing list
> OpenStack-operators@lists.openstack.org
> 

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

[Doug Hellmann]

Excerpts from Morgenstern, Chad's message of 2017-08-10 13:01:47 +:
> I tried to convert all docs to rst using pandoc as the following example shows
> pandoc -f docbook -t rst -s section_cinder-deployment-choices.xml -o 
> section_cinder-deployment-choices.rst
> 
> There were no errors thrown, however we are missing things such as section 
> headers, and the internal links did not convert either.
> 
> Please advise how to address this issue?

Yuki Kasuya is also working on this (see the thread "Operations Guide
removal" on this list. Maybe you can collaborate?

Doug

> 
> P.S.
> By way of example: 
> 
> 
> For example, in the rst doc these are this is what we have
> debian@debian-1:~/openstack-repo/openstack-deploy-ops-guide/cinder$ egrep -B 
> 1 "^\*\*|^\-\-|^==" section_cinder-deployment-choices.rst | egrep -v '^-'  | 
> grep -v "^$"
> Theory of Operation & Deployment Choices
> 
> **Cinder Backends and Storage Virtual Machines.**
> **Cinder volumes and FlexVol volumes.**
> **Cinder volume representation within a FlexVol volume.**
> **Cinder Scheduling and resource pool selection.**
> **Cinder snapshots versus NetApp Snapshots.**
> **E-Series snapshots.**
> **CDOT and 7-mode consistency groups.**
> **E-Series consistency groups.**
> **SANtricity Web Services Proxy.**
> **FAS.**
> **E-Series.**
> **iSCSI.**
> **NFS.**
> **Volume Groups.**
> **Dynamic Disk Pools (DDP).**
> **Options.**
> **Setup.**
> **Filer Side Setup.**
> **OpenStack Setup.**
> **Data ONTAP Thin Provisioning.**
> **E-Series Thin Provisioning.**
> **Establishing an iSCSI Session.**
> **iSCSI Session Scope.**
> **Configuration Options.**
> 
> Where as in the original xml file:
> debian@debian-1:~/openstack-repo/openstack-deploy-ops-guide/cinder$ grep -i 
> title section_cinder-deployment-choices.xml
> Theory of Operation  Deployment Choices
> Construct Mappings between Cinder and Data ONTAP
> Cinder Backends and Storage Virtual Machines
> Cinder volumes and FlexVol volumes
> Cinder volume representation within a FlexVol 
> volume
> Cinder Scheduling and resource pool selection
> Cinder snapshots versus NetApp Snapshots
> E-Series snapshots
> CDOT and 7-mode consistency groups
> E-Series consistency groups
> SANtricity Web 
> Services Proxy
> SANtricity Web 
> Services Proxy
> Mitaka Support
> Recommendation
> Deployment Choice: FAS vs E-Series
> FAS
> E-Series
> Deployment Choice: Clustered Data ONTAP vs Data ONTAP 
> operating in 7-Mode
> Recommendation
> Deployment Choice: NFS versus iSCSI
> iSCSI
> NFS
> Recommendation
> Recommendation
> Deployment Choice: Volume Groups vs Dynamic Disk Pools 
> (E-Series)
> Volume Groups
> Dynamic Disk Pools (DDP)
> Recommendation
> Deployment Choice: NFS Security
> Options
>   Setup
>   Filer Side Setup
>   OpenStack Setup
> Fibre Channel Switch Fabric With Cinder
> Using Cinder Volume Types to Create a Storage Service 
> Catalog
> Over-Subscription and Thin-Provisioning
>   Data ONTAP Thin Provisioning
>   E-Series Thin Provisioning
> Unidirectional CHAP Authentication
>   Establishing an iSCSI Session
>       iSCSI Session Scope
>   Configuration Options
> 
> -Original Message-
> From: Doug Hellmann [mailto:d...@doughellmann.com] 
> Sent: Thursday, August 10, 2017 8:37 AM
> To: openstack-operators <openstack-operators@lists.openstack.org>
> Subject: Re: [Openstack-operators] [OpenStack-docs] [doc] Operations Guide 
> removal
> 
> 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

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

[Morgenstern, Chad]

I tried to convert all docs to rst using pandoc as the following example shows
pandoc -f docbook -t rst -s section_cinder-deployment-choices.xml -o 
section_cinder-deployment-choices.rst

There were no errors thrown, however we are missing things such as section 
headers, and the internal links did not convert either.

Please advise how to address this issue?

P.S.
By way of example: 


For example, in the rst doc these are this is what we have
debian@debian-1:~/openstack-repo/openstack-deploy-ops-guide/cinder$ egrep -B 1 
"^\*\*|^\-\-|^==" section_cinder-deployment-choices.rst | egrep -v '^-'  | grep 
-v "^$"
Theory of Operation & Deployment Choices

**Cinder Backends and Storage Virtual Machines.**
**Cinder volumes and FlexVol volumes.**
**Cinder volume representation within a FlexVol volume.**
**Cinder Scheduling and resource pool selection.**
**Cinder snapshots versus NetApp Snapshots.**
**E-Series snapshots.**
**CDOT and 7-mode consistency groups.**
**E-Series consistency groups.**
**SANtricity Web Services Proxy.**
**FAS.**
**E-Series.**
**iSCSI.**
**NFS.**
**Volume Groups.**
**Dynamic Disk Pools (DDP).**
**Options.**
**Setup.**
**Filer Side Setup.**
**OpenStack Setup.**
**Data ONTAP Thin Provisioning.**
**E-Series Thin Provisioning.**
**Establishing an iSCSI Session.**
**iSCSI Session Scope.**
**Configuration Options.**

Where as in the original xml file:
debian@debian-1:~/openstack-repo/openstack-deploy-ops-guide/cinder$ grep -i 
title section_cinder-deployment-choices.xml
Theory of Operation  Deployment Choices
Construct Mappings between Cinder and Data ONTAP
Cinder Backends and Storage Virtual Machines
Cinder volumes and FlexVol volumes
Cinder volume representation within a FlexVol volume
Cinder Scheduling and resource pool selection
Cinder snapshots versus NetApp Snapshots
E-Series snapshots
CDOT and 7-mode consistency groups
E-Series consistency groups
SANtricity Web 
Services Proxy
SANtricity Web 
Services Proxy
Mitaka Support
Recommendation
Deployment Choice: FAS vs E-Series
FAS
E-Series
Deployment Choice: Clustered Data ONTAP vs Data ONTAP operating 
in 7-Mode
Recommendation
Deployment Choice: NFS versus iSCSI
iSCSI
NFS
Recommendation
Recommendation
Deployment Choice: Volume Groups vs Dynamic Disk Pools 
(E-Series)
Volume Groups
Dynamic Disk Pools (DDP)
Recommendation
Deployment Choice: NFS Security
Options
  Setup
  Filer Side Setup
  OpenStack Setup
Fibre Channel Switch Fabric With Cinder
Using Cinder Volume Types to Create a Storage Service 
Catalog
Over-Subscription and Thin-Provisioning
  Data ONTAP Thin Provisioning
  E-Series Thin Provisioning
Unidirectional CHAP Authentication
  Establishing an iSCSI Session
  iSCSI Session Scope
  Configuration Options

-Original Message-
From: Doug Hellmann [mailto:d...@doughellmann.com] 
Sent: Thursday, August 10, 2017 8:37 AM
To: openstack-operators <openstack-operators@lists.openstack.org>
Subject: Re: [Openstack-operators] [OpenStack-docs] [doc] Operations Guide 
removal

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
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
___
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

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

[Anne Gentle]

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



-- 

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

___
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

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

[Doug Hellmann]

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
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

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

[Anne Gentle]

On Wed, Jul 19, 2017 at 5:51 AM, Doug Hellmann  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
> OpenStack-operators@lists.openstack.org
> 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
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

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

[Alexandra Settle]

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"  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  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
> openstack-d...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
Cheers,
~Blairo


___
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators

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

[Blair Bethwaite]

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  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
> openstack-d...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
Cheers,
~Blairo

___
OpenStack-operators mailing list
OpenStack-operators@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators