On 23/05/14 08:56, Anne Gentle wrote: > > > > On Tue, May 20, 2014 at 6:42 PM, Steve Baker <sba...@redhat.com > <mailto:sba...@redhat.com>> wrote: > > On 21/05/14 02:31, Doug Hellmann wrote: >> On Fri, May 16, 2014 at 2:10 PM, Gauvain Pocentek >> <gauvain.pocen...@objectif-libre.com> >> <mailto:gauvain.pocen...@objectif-libre.com> wrote: >>> Le 2014-05-16 17:13, Anne Gentle a écrit : >>> >>>> On Thu, May 15, 2014 at 10:34 AM, Gauvain Pocentek >>>> <gauvain.pocen...@objectif-libre.com> >>>> <mailto:gauvain.pocen...@objectif-libre.com> wrote: >>>> >>>>> Hello, >>>>> >>>>> This mail probably mainly concerns the doc team, but I guess that the >>>>> heat team wants to know what's going on. >>>>> >>>>> We've shortly discussed the state of heat documentation with Anne >>>>> Gentle >>>>> and Andreas Jaeger yesterday, and I'd like to share what we think >>>>> would be >>>>> nice to do. >>>>> >>>>> Currently we only have a small section in the user guide that >>>>> describes >>>>> how to start a stack, but nothing documenting how to write templates. >>>>> The >>>>> heat developer doc provides a good reference, but I think it's not >>>>> easy to >>>>> use to get started. >>>>> >>>>> So the idea is to add an "OpenStack Orchestration" chapter in the user >>>>> guide that would document how to use a cloud with heat, and how to >>>>> write >>>>> templates. >>>>> >>>>> I've drafted a spec to keep track of this at [0]. >>>> I'd like to experiment a bit with converting the End User Guide to an >>>> easier markup to enable more contributors to it. Perhaps bringing in >>>> Orchestration is a good point to do this, plus it may help address the >>>> auto-generation Steve mentions. >>>> >>>> The loss would be the single sourcing of the End User Guide and Admin >>>> User Guide as well as loss of PDF output and loss of translation. If >>>> these losses are worthwhile for easier maintenance and to encourage >>>> contributions from more cloud consumers, then I'd like to try an >>>> experiment with it. >>> Using RST would probably make it easier to import/include the >>> developers' >>> documentation. But I'm not sure we can afford to loose the features you >>> mention. Translations for the user guides are very important I think. >> Sphinx does appear to have translation support: >> http://sphinx-doc.org/intl.html?highlight=translation >> >> I've never used the feature myself, so I don't know how good the >> workflow is. >> >> Sphinx will generate PDFs, though the LaTeX output is not as nice >> looking as what we get now. There's also a direct-to-pdf builder that >> uses rst2pdf that appears to support templates, so that might be an >> easier path to producing something attractive: >> http://ralsina.me/static/manual.pdf > I attempted to make latexpdf on the heat sphinx docs and fell down > a latex tool-chain hole. > > I tried adding rst2pdf support to the sphinx docs build: > https://review.openstack.org/#/c/94491/ > > and the results are a reasonable start: > > https://drive.google.com/file/d/0B_b9ckHiNkjVS3ZNZmNXMkJkWE0/edit?usp=sharing > > > >>> How would we review changes made in "external" repositories? The user >>> guides >>> are continuously published, this means that a change done in the >>> heat/docs/ >>> dir would quite quickly land on the webserver without a doc team >>> review. I >>> completely trust the developers, but I'm not sure that this is the way >>> to >>> go. >>> >>> >>>> The experiment would be to have a new repo set up, >>>> openstack/user-guide and use the docs-core team as reviewers on it. >>>> Convert the End User Guide from DocBook to RST and build with Sphinx. >>>> Use the oslosphinx tempate for output. But what I don't know is if >>>> it's possible to build the automated output outside of the >>>> openstack/heat repo, does anyone have interest in doing a proof of >>>> concept on this? >>> I'm not sure that this is possible, but I'm no RST expert. >> I'm not sure this quite answers the question, but the RST directives >> for auto-generating docs from code usually depend on being able to >> import the code. That means heat and its dependencies would need to be >> installed on the system where the build is performed. We accomplish >> this in the dev doc builds by using tox, which automatically handles >> the installation as part of setting up the virtualenv where the build >> command runs. > I'm sure we could do a git checkout of heat during the docs build, > and even integrate that with gating. I thought this was already > happening for some docbook builds, but I can't find any examples now. > >>>> I'd also like input on the loss of features I'm describing above. Is >>>> this worth experimenting with? >>> Starting this new book sounds like a lot of work. Right now I'm not >>> convinced it's worth it. >>> >>> > How about this for a suggestion. The Heat template authoring guide > is potentially so large and different that it deserves to be in > its own document. It is aimed at users, but there is so much > potential content hidden in the template format that it wouldn't > necessarily belong in the current user guide. > > > Sorry, every doc team member I've talked to doesn't want to take on > another guide. > > Also the loss of nice PDF and having to test and maintain a second > translation tool chain isn't enthusiastically embraced from what I'm > hearing. > > > > We could start a new doc repo which is a sphinx-based template > authoring guide. It will have a bunch of manually written content > plus resource reference built from a heat git checkout. > > > Since we already have a template authoring guide living with the heat > repo so this doesn't sound that much different from today. > > If this all works out then we can consider adding the user guide > content to the heat template authoring guide, resulting in a new > merged sphinx-based user guide. > > > Is the benefit a chance to experiment further? That might be useful, > but let's talk about what we'd use to measure success of this guide. > Page views? User input through bugs logged? Other ideas? > > The only significant success criteria I can think of is an increase in contributions from xml-phobic developers. But for all that, RST is quite complicated for a "simple" markup.
_______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev