<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Tue, May 20, 2014 at 6:42 PM, Steve Baker <span dir="ltr"><<a href="mailto:sbaker@redhat.com" target="_blank">sbaker@redhat.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000"><div><div class="h5">
<div>On 21/05/14 02:31, Doug Hellmann wrote:<br>
</div>
<blockquote type="cite">
<pre>On Fri, May 16, 2014 at 2:10 PM, Gauvain Pocentek
<a href="mailto:gauvain.pocentek@objectif-libre.com" target="_blank"><gauvain.pocentek@objectif-libre.com></a> wrote:
</pre>
<blockquote type="cite">
<pre>Le 2014-05-16 17:13, Anne Gentle a écrit :
</pre>
<blockquote type="cite">
<pre>On Thu, May 15, 2014 at 10:34 AM, Gauvain Pocentek
<a href="mailto:gauvain.pocentek@objectif-libre.com" target="_blank"><gauvain.pocentek@objectif-libre.com></a> wrote:
</pre>
<blockquote type="cite">
<pre>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].
</pre>
</blockquote>
<pre>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.
</pre>
</blockquote>
<pre>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.
</pre>
</blockquote>
<pre>Sphinx does appear to have translation support:
<a href="http://sphinx-doc.org/intl.html?highlight=translation" target="_blank">http://sphinx-doc.org/intl.html?highlight=translation</a>
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:
<a href="http://ralsina.me/static/manual.pdf" target="_blank">http://ralsina.me/static/manual.pdf</a>
</pre>
</blockquote></div></div>
I attempted to make latexpdf on the heat sphinx docs and fell down a
latex tool-chain hole.<br>
<br>
I tried adding rst2pdf support to the sphinx docs build:<br>
<a href="https://review.openstack.org/#/c/94491/" target="_blank">https://review.openstack.org/#/c/94491/</a><br>
<br>
and the results are a reasonable start:<br>
<a href="https://drive.google.com/file/d/0B_b9ckHiNkjVS3ZNZmNXMkJkWE0/edit?usp=sharing" target="_blank">https://drive.google.com/file/d/0B_b9ckHiNkjVS3ZNZmNXMkJkWE0/edit?usp=sharing</a><div class=""><br>
<br>
<blockquote type="cite">
<pre></pre>
<blockquote type="cite">
<pre>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.
</pre>
<blockquote type="cite">
<pre>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?
</pre>
</blockquote>
<pre>I'm not sure that this is possible, but I'm no RST expert.
</pre>
</blockquote>
<pre>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.
</pre>
</blockquote></div>
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.<div class=""><br>
<blockquote type="cite">
<pre></pre>
<blockquote type="cite">
<pre></pre>
<blockquote type="cite">
<pre>I'd also like input on the loss of features I'm describing above. Is
this worth experimenting with?
</pre>
</blockquote>
<pre>Starting this new book sounds like a lot of work. Right now I'm not
convinced it's worth it.
</pre>
</blockquote>
</blockquote></div>
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.<br></div></blockquote><div><br></div><div>Sorry, every doc team member I've talked to doesn't want to take on another guide. </div><div><br></div><div>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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000">
<br>
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. </div></blockquote><div><br></div><div>Since we already have a template authoring guide living with the heat repo so this doesn't sound that much different from today. <br>
</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000">
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.<br>
<br></div></blockquote><div><br></div><div>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?<br>
</div><div><br></div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div bgcolor="#FFFFFF" text="#000000">
Opinions?<br>
</div>
<br>_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><br></div></div>