<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, May 8, 2014 at 9:06 AM, Christian Berendt <span dir="ltr"><<a href="mailto:berendt@b1-systems.de" target="_blank">berendt@b1-systems.de</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>On 05/07/2014 10:43 PM, Roger Luethi 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">
The people who are qualified to contribute to the docs are usually not<br>
non-technical people, but they can't spend hours setting up an environment<br>
just to work on docs. IMHO good documentation (or scripts, or VM downloads)<br>
that make it easy to create a complete, working environment for testing and<br>
building documentation would go a long way towards making contributions<br>
easier.<br>
</blockquote>
<br></div>
NOTE: The box will soon be available.<br>
<br>
I think it's a good idea to have an isolated virtual environment for testing and building the documentation.<br></blockquote><div><br></div><div>I think this is cool, but to give an idea of some of the comments, I think people are having trouble testing OpenStack itself to make sure the docs are accurate. Examples:</div>

<br>"Not sure I have the appropriate expertise."<br>"...while I know how a system should be *configured*, I know little about the *install* process."<br>"...it's often so much work to get a proper patch in because there are often so many calls that need to be made just to get to the point of where you want to make the fix. e.g. To create a Neutron port you first need to create a Net and then a Subnet and there are ton of little bits of info necessary for those calls. It becomes a non-starter, when you're strapped for time. The problem is intrinsic to deep APIs so I've got no idea what could help here."
<div><br></div><div>Also, to clarify, I believe there's more hesitation and doubt around WADL than DocBook echoed in the survey.</div><div><br></div><div>I love this idea of a vagrant box for building docs though, will review!</div>

<div><br></div><div>Thanks,</div><div>Anne</div><div><br></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">


<br>
Just created an initial Vagrant box that can be used for testing and building the documentation inside a virtual system.<br>
<br>
It includes Maven and tox. All documentation repositories (+ openstack-doc-tools) are already pulled (located in /opt/working) and all Maven dependencies are downloaded.<br>
<br>
There are three scripts available (located in /usr/local/bin) to simplify some doings:<br>
<br>
  * pull.sh: runs git pull in every repository<br>
  * fetch.sh: runs mvn dependency:copy-dependencies in every directory including a pom.xml<br>
  * build.sh: builds a specified document in a specified repository<br>
<br>
For example to build the document admin-guide-cloud in the repository openstack-manuals run build.sh openstack-manuals admin-guide-cloud.<br>
<br>
The box has a directory "/opt/working" that's synced to the local directory working on the workstation. This way it's possible to edit and commit the files using the already available toolchain on the workstation and to test and build the documents inside the virtual system.<br>



<br>
As a nit port 8080 on the workstation is forwarded to port 80 on the virtual system. Port 80 simply serves the files located in /opt/working using Nginx. To view the local-files.html simply go to <a href="http://localhost:8080/openstack-manuals/doc/" target="_blank">http://localhost:8080/<u></u>openstack-manuals/doc/</a>.<br>



<br>
Christian.<br>
<br>
-- <br>
Christian Berendt<br>
Cloud Computing Solution Architect<br>
Mail: <a href="mailto:berendt@b1-systems.de" target="_blank">berendt@b1-systems.de</a><br>
<br>
B1 Systems GmbH<br>
Osterfeldstraße 7 / 85088 Vohburg / <a href="http://www.b1-systems.de" target="_blank">http://www.b1-systems.de</a><br>
GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537<br>
<br>
______________________________<u></u>_________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.<u></u>openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/<u></u>cgi-bin/mailman/listinfo/<u></u>openstack-docs</a><br>
</blockquote></div><br></div></div>