Open Stack

On 23/05/14 08:56, Anne Gentle wrote:
>
>
>
> On Tue, May 20, 2014 at 6:42 PM, Steve Baker <sbaker at redhat.com
> <mailto:sbaker at redhat.com>> wrote:
>
>     On 21/05/14 02:31, Doug Hellmann wrote:
>>     On Fri, May 16, 2014 at 2:10 PM, Gauvain Pocentek
>>     <gauvain.pocentek at objectif-libre.com> <mailto:gauvain.pocentek at 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.pocentek at objectif-libre.com> <mailto:gauvain.pocentek at 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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140523/b27751fd/attachment.html>