Re: [openstack-dev] [DevStack] Proposal - add support for Markdown for docs

2014-10-27 Thread Sean Dague
On 10/22/2014 11:10 AM, Collins, Sean wrote:
 With some xargs, sed, and pandoc - I now present to you the first
 attempt at converting the DevStack docs to RST, and making the doc build
 look similar to other projects.
 
 https://review.openstack.org/130241
 
 It is extremely rough, I basically ran everything through Pandoc and
 cleaned up any errors that Sphinx spat out. I'm sure there is a lot of
 work that needs to be done to format it to be more readable - but I'm
 pretty pleased with the result.

+2, you are awesome for taking this on! Thanks much.

-Sean

-- 
Sean Dague
http://dague.net

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


Re: [openstack-dev] [DevStack] Proposal - add support for Markdown for docs

2014-10-27 Thread Mike Spreitzer
Sean Dague s...@dague.net wrote on 10/27/2014 09:13:27 AM:

 From: Sean Dague s...@dague.net
 
 On 10/22/2014 11:10 AM, Collins, Sean wrote:
  With some xargs, sed, and pandoc - I now present to you the first
  attempt at converting the DevStack docs to RST, and making the doc 
build
  look similar to other projects.
  
  https://review.openstack.org/130241
  
  It is extremely rough, I basically ran everything through Pandoc and
  cleaned up any errors that Sphinx spat out. I'm sure there is a lot of
  work that needs to be done to format it to be more readable - but I'm
  pretty pleased with the result.
 
 +2, you are awesome for taking this on! Thanks much.
 
-Sean

Yes, thank you very much --- both for the doc infrastructure and the docs 
that you will write using it.

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


Re: [openstack-dev] [DevStack] Proposal - add support for Markdown for docs

2014-10-22 Thread Collins, Sean
With some xargs, sed, and pandoc - I now present to you the first
attempt at converting the DevStack docs to RST, and making the doc build
look similar to other projects.

https://review.openstack.org/130241

It is extremely rough, I basically ran everything through Pandoc and
cleaned up any errors that Sphinx spat out. I'm sure there is a lot of
work that needs to be done to format it to be more readable - but I'm
pretty pleased with the result.

-- 
Sean M. Collins
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [DevStack] Proposal - add support for Markdown for docs

2014-10-22 Thread Jeremy Stanley
On 2014-10-21 17:00:09 + (+), Jeremy Stanley wrote:
 Well, actually that's still in progress. The last bit we need is to
 host a redirect somewhere so that devstack.org/(.*) is 301'd to
 docs.openstack.org/developer/devstack/$1 instead, and then we change
 the DNS address records to point to wherever we stuck that redirect.

Redirect is implemented with https://review.openstack.org/130001 so
once that's approved and merges I'll update DNS entries accordingly.
-- 
Jeremy Stanley

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


[openstack-dev] [DevStack] Proposal - add support for Markdown for docs

2014-10-21 Thread Collins, Sean
Hi,

I have a lot of documentation around DevStack and some configurations
that I run for a multi-node lab, that uses Neutron and IPv6. I would
love to contribute to them, but they are currently in Markdown format.

Looking at the current docs, they are all currently in raw HTML, and I
was hoping that it would be possible to add Pelican[1], which would make
it easier to contribute documentation since we wouldn't have to write
raw HTML. This may help make contributing docs more seamless.

What does everyone think?

[1]: http://blog.getpelican.com/


-- 
Sean M. Collins
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [DevStack] Proposal - add support for Markdown for docs

2014-10-21 Thread Dean Troyer
On Tue, Oct 21, 2014 at 9:58 AM, Collins, Sean 
sean_colli...@cable.comcast.com wrote:

 Looking at the current docs, they are all currently in raw HTML, and I
 was hoping that it would be possible to add Pelican[1], which would make
 it easier to contribute documentation since we wouldn't have to write
 raw HTML. This may help make contributing docs more seamless.


Sean, I assume you realize that by standing up and saying this you become
the first volunteer to do the work, right? ;)

Seriously, I wouldn't be against something like this and in fact would
rather like to refresh the HTML docs.  Now that devstack.org is generated
on each commit again (thanks anteaya!) we have the ability to do so.

Questions that come to mind for further discussion:

* Is there a 'good enough' reason to do something new that is different
from the rest of docs.openstack.org?  Bringing in the legacy site is one
thing, we should have a good reason for adding yet another new build
dependency.

* I'm interested in the opinions of the readership if the shocco-generated
script pages are useful.  One of the reasons DevStack is in shell script is
to make it readable by everyone and the literate-style formatting is to
help with that.

dt

-- 

Dean Troyer
dtro...@gmail.com
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [DevStack] Proposal - add support for Markdown for docs

2014-10-21 Thread Collins, Sean
I do see mentions of gh-pages in the build_docs.sh script - is
devstack.org redirect to GitHub?

-- 
Sean M. Collins
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [DevStack] Proposal - add support for Markdown for docs

2014-10-21 Thread Collins, Sean
On Tue, Oct 21, 2014 at 11:33:44AM EDT, Dean Troyer wrote:
 On Tue, Oct 21, 2014 at 9:58 AM, Collins, Sean 
 sean_colli...@cable.comcast.com wrote:
 
  Looking at the current docs, they are all currently in raw HTML, and I
  was hoping that it would be possible to add Pelican[1], which would make
  it easier to contribute documentation since we wouldn't have to write
  raw HTML. This may help make contributing docs more seamless.
 
 
 Sean, I assume you realize that by standing up and saying this you become
 the first volunteer to do the work, right? ;)

Yep - I already have a branch that adds it as a dependency, and I'm
starting to hack on it right now, I just figured I'd check on the ML
and see core reviewer blessings :)


-- 
Sean M. Collins
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [DevStack] Proposal - add support for Markdown for docs

2014-10-21 Thread Monty Taylor
On 10/21/2014 10:37 AM, Collins, Sean wrote:
 I do see mentions of gh-pages in the build_docs.sh script - is
 devstack.org redirect to GitHub?
 

Nope - it used to be. It's now built and published like the rest of
openstack docs.

Now - I don't want to get in the way of the work you're wanting to
contribute, because I'm pretty sure that's awesome ... but all of the
rest of the OpenStack docs are in RST and not MD, so it seems strange to
do new work in a different format.

That said - devstack is a bit different of a beast, so maybe it doesn't
matter?

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


Re: [openstack-dev] [DevStack] Proposal - add support for Markdown for docs

2014-10-21 Thread Collins, Sean
On Tue, Oct 21, 2014 at 11:59:12AM EDT, Monty Taylor wrote:
 On 10/21/2014 10:37 AM, Collins, Sean wrote:
  I do see mentions of gh-pages in the build_docs.sh script - is
  devstack.org redirect to GitHub?
  
 
 Nope - it used to be. It's now built and published like the rest of
 openstack docs.
 
 Now - I don't want to get in the way of the work you're wanting to
 contribute, because I'm pretty sure that's awesome ... but all of the
 rest of the OpenStack docs are in RST and not MD, so it seems strange to
 do new work in a different format.
 

Actually after I sent the e-mail I checked, and Pelican supports
multiple formats, including RST. Changing from Markdown to RST isn't
too onerous - I'd rather go from Markdown - RST than Markdown - HTML.

Thinking a little more, it may be worth cribbing the code from other
projects, like how the *-specs repos are generating docs from RST files
rather than importing Pelican?


-- 
Sean M. Collins
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [DevStack] Proposal - add support for Markdown for docs

2014-10-21 Thread Kyle Mestery
On Tue, Oct 21, 2014 at 11:12 AM, Collins, Sean
sean_colli...@cable.comcast.com wrote:
 On Tue, Oct 21, 2014 at 11:59:12AM EDT, Monty Taylor wrote:
 On 10/21/2014 10:37 AM, Collins, Sean wrote:
  I do see mentions of gh-pages in the build_docs.sh script - is
  devstack.org redirect to GitHub?
 

 Nope - it used to be. It's now built and published like the rest of
 openstack docs.

 Now - I don't want to get in the way of the work you're wanting to
 contribute, because I'm pretty sure that's awesome ... but all of the
 rest of the OpenStack docs are in RST and not MD, so it seems strange to
 do new work in a different format.


 Actually after I sent the e-mail I checked, and Pelican supports
 multiple formats, including RST. Changing from Markdown to RST isn't
 too onerous - I'd rather go from Markdown - RST than Markdown - HTML.

 Thinking a little more, it may be worth cribbing the code from other
 projects, like how the *-specs repos are generating docs from RST files
 rather than importing Pelican?

That seems like a reasonable starting place to me. :)


 --
 Sean M. Collins
 ___
 OpenStack-dev mailing list
 OpenStack-dev@lists.openstack.org
 http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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


Re: [openstack-dev] [DevStack] Proposal - add support for Markdown for docs

2014-10-21 Thread Jeremy Stanley
On 2014-10-21 10:59:12 -0500 (-0500), Monty Taylor wrote:
 On 10/21/2014 10:37 AM, Collins, Sean wrote:
  I do see mentions of gh-pages in the build_docs.sh script - is
  devstack.org redirect to GitHub?
 
 Nope - it used to be. It's now built and published like the rest of
 openstack docs.
[...]

Well, actually that's still in progress. The last bit we need is to
host a redirect somewhere so that devstack.org/(.*) is 301'd to
docs.openstack.org/developer/devstack/$1 instead, and then we change
the DNS address records to point to wherever we stuck that redirect.
-- 
Jeremy Stanley

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