Re: [openstack-dev] [DevStack] Proposal - add support for Markdown for docs
Sean Dague wrote on 10/27/2014 09:13:27 AM: > From: 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 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
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
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
Re: [openstack-dev] [DevStack] Proposal - add support for Markdown for docs
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
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
Re: [openstack-dev] [DevStack] Proposal - add support for Markdown for docs
On Tue, Oct 21, 2014 at 11:12 AM, Collins, Sean 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
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
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
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
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
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
[openstack-dev] [DevStack] Proposal - add support for Markdown for docs
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
