Difference between revisions of "Documentation/HowTo"
| Line 3: | Line 3: | ||
At the core of OpenStack is the community and collaboration that we do - the same rules for the code apply to documentation too. Ideally any code contribution that is merged into the base has documentation to go with it. Anne Gentle is the coordinator for all documentation efforts, both community-based and "official" docs. This page describes the methods we use to create the basis for world-class documentation for OpenStack developers and users. | At the core of OpenStack is the community and collaboration that we do - the same rules for the code apply to documentation too. Ideally any code contribution that is merged into the base has documentation to go with it. Anne Gentle is the coordinator for all documentation efforts, both community-based and "official" docs. This page describes the methods we use to create the basis for world-class documentation for OpenStack developers and users. | ||
| − | |||
| − | |||
== Tools Overview == | == Tools Overview == | ||
| Line 56: | Line 54: | ||
The workflow for documentation matches the workflow for code - you download a branch, work on it locally, then commit the changes and propose a merge. Your changes are merged into the main, published doc base, and the doc is built to its varying outputs. | The workflow for documentation matches the workflow for code - you download a branch, work on it locally, then commit the changes and propose a merge. Your changes are merged into the main, published doc base, and the doc is built to its varying outputs. | ||
| − | === Detailed Workflow with | + | === Detailed Workflow with Github and Gerrit === |
| − | The page I always refer to for using | + | The page I always refer to for using Git and Gerrit for daily tasks is |
| − | http://wiki.openstack.org/ | + | http://wiki.openstack.org/GerritWorkflow. |
| − | + | The workflow takes some startup work. First, you make a Launchpad account, and upload a public key. Then, you identify your Launchpad account to the git command line and away you go. You also need a Github account but the Launchpad account contains the signon and permissions information for the Gerrit workflow that we use for reviews. | |
Here's a sample for the documentation project specifically, once you get the Launchpad account set up. | Here's a sample for the documentation project specifically, once you get the Launchpad account set up. | ||
| Line 69: | Line 67: | ||
<pre><nowiki> | <pre><nowiki> | ||
| − | mkdir ~/src/ | + | mkdir ~/src/docs |
| − | cd ~/src/ | + | cd ~/src/docs |
</nowiki></pre> | </nowiki></pre> | ||
| − | + | Follow the steps in [[GerritWorkflow]], using openstack-manuals as the project name for the Admin manuals, and project-api, such as compute-api, for the project name for API guides. | |
| + | |||
| + | Now you can check out all the files for the admin doc project: | ||
<pre><nowiki> | <pre><nowiki> | ||
| − | + | git clone git://github.com/openstack/openstack-manuals.git | |
</nowiki></pre> | </nowiki></pre> | ||
| − | |||
| − | + | Set up the Gerrit Change-Id hook, which is used for reviews, and run git review to run a script in the /tools directory which sets up the remote repository correctly: | |
<pre><nowiki> | <pre><nowiki> | ||
| − | + | cd $PROJECT | |
| + | git review | ||
</nowiki></pre> | </nowiki></pre> | ||
| − | Now you | + | Now make sure you have the latest from Github (docs move more slowly than code, but this is a good practice). |
<pre><nowiki> | <pre><nowiki> | ||
| − | + | git checkout master | |
| + | git pull origin master | ||
</nowiki></pre> | </nowiki></pre> | ||
| − | + | Lastly, create a branch to do your work in that you'll do commits from: | |
<pre><nowiki> | <pre><nowiki> | ||
| − | + | git checkout -b TOPIC-BRANCH | |
</nowiki></pre> | </nowiki></pre> | ||
| − | + | ||
| + | Edit happily! You can use [http://www.oxygenxml.com/ Oxygen] since you're working on an open source project and we acknowledge their support. | ||
| + | |||
| + | When you're done with edits, if you've added any files do this in the working directory: | ||
<pre><nowiki> | <pre><nowiki> | ||
| − | + | git add . | |
</nowiki></pre> | </nowiki></pre> | ||
| − | Next, you commit your changes with a message that'll be displayed in | + | |
| + | Next, you commit your changes with a message that'll be displayed in review.openstack.org, creating a change set: | ||
<pre><nowiki> | <pre><nowiki> | ||
| − | + | git commit -a -m 'Here's what I did in this set of changes' | |
</nowiki></pre> | </nowiki></pre> | ||
| − | Next, push your changes | + | |
| + | Next, push your changes for review with: | ||
<pre><nowiki> | <pre><nowiki> | ||
| − | + | git review | |
</nowiki></pre> | </nowiki></pre> | ||
| − | Go to the | + | |
| + | Go to the review site itself to request a merge with the openstack-manuals project, at review.openstack.org. One of the core doc team members will review your edits and let you know if any changes are needed prior to merging them in. | ||
To generate the PDF and webhelp within your local environment, install Maven. To run the pom file within the mvnbuild directory, which builds the Maven mojo, you run mvn install. Then, switch to the doc/ directory, and run mvn generate-sources using that pom.xml, to build the docs themselves. | To generate the PDF and webhelp within your local environment, install Maven. To run the pom file within the mvnbuild directory, which builds the Maven mojo, you run mvn install. Then, switch to the doc/ directory, and run mvn generate-sources using that pom.xml, to build the docs themselves. | ||
You may need a modified settings.xml and if you already have M2_HOME set, you might see an error about "java.lang.[[ClassNotFoundException]]: org.codehaus.plexus.classworlds.launcher.Launcher" - just run unset M2_HOME. | You may need a modified settings.xml and if you already have M2_HOME set, you might see an error about "java.lang.[[ClassNotFoundException]]: org.codehaus.plexus.classworlds.launcher.Launcher" - just run unset M2_HOME. | ||
| + | |||
| + | == Tools == | ||
| + | |||
| + | Thanks to the generosity of Oxygen in supporting open source projects, you can edit DocBook XML within the Oxygen Author or Editor by downloading a copy of the software from http://www.oxygenxml.com/. | ||
== Translation == | == Translation == | ||
Revision as of 14:45, 28 September 2011
How To Work on OpenStack Documentation
At the core of OpenStack is the community and collaboration that we do - the same rules for the code apply to documentation too. Ideally any code contribution that is merged into the base has documentation to go with it. Anne Gentle is the coordinator for all documentation efforts, both community-based and "official" docs. This page describes the methods we use to create the basis for world-class documentation for OpenStack developers and users.
Tools Overview
Currently, we use this wiki, RST files stored in source code, (ReStructured Text, it has a similar text-based markup as wikitext) and DocBook to create OpenStack's web documentation.
The wiki is easy-peasy, you just request an account on wiki.openstack.org by emailing anne at openstack dot org, create a new page, and start editing.
Editing RST or DocBook has a few more steps and depends on whether the repository is still housed in Launchpad or has moved to Github. For Launchpad, where openstack-manuals still resides, you create a Launchpad account, install Bazaar (see http://wiki.openstack.org/LifeWithBzrAndLaunchpad) and get the code so you can work on the doc directory in any project, namely nova, swift, glance, or openstack-manuals. To work on the DocBook source files, a working project exists in Launchpad in the openstack-manuals project since DocBook documentation encompasses all three OpenStack projects. All API documentation has been moved to Github, and is housed in image-api, identity-api, compute-api, and object-api projects there. For Github hosted docs, you get a Github account and use git for checking in and out docs.
The RST source is built into html using Sphinx so that it gets displayed on nova.openstack.org, swift.openstack.org, and glance.openstack.org.
The DocBook source is built into html (webhelp) and PDF using XSLT transforms included with the DocBook project.
A super light-weight drafting option, easy as a click-through, is to write with other collaborators on an Etherpad at http://etherpad.openstack.org/. We can invite others as we go, and choose to write it as wikitext, RST, or docbook.
#!rst wiki.openstack.org (wikitext or RST) ------------------------------------- The OpenStack wiki contains draft documentation but should ideally contain project docs, specs, doc drafts, and outlines. Any dev or user doc on the wiki is subject to constant change so if there's a page you want to keep an eye on (like Nova installations for example), add it to your Notifications list (under User > Settings > Notifications in the wiki). I've also begun a copy/paste effort to put RST in wiki pages to avoid multiple maintenance on pages that are also housed on nova.openstack.org, for example. There are great pages on the wiki that I want to take to the other doc sites, for example the Nova deploy page on the wiki should be highlighted in other locations as well. nova.openstack.org, swift.openstack.org, glance.openstack.org (RST) ------------------------------------------------------------------- The RST pages stored with the project code should be written with a developer audience in mind, although many times you'll find there is overlap in what an admin needs to know and what a developer needs to know. High priorities for those sites are wider coverage of doc strings, API doc, i18N methodology, and architecture concepts that'll help developers. docs.openstack.org (DocBook) ---------------------------- The source for this site is housed in a Launchpad project at http://launchpad.net/openstack-manuals. You can either build the output locally if you want or just submit changes to the source XML through merge proposals. The !OpenStack Jenkins build server builds the doc and copies the output to docs.openstack.org/trunk automatically thanks to the pom.xml files included in the source files. * doc/source/docbkx contains the DocBook XML source files and images * doc/build/mvnbuild contains the OpenStack transforms to create the PDF and HTML using pom.xml build file I can also build to docs.openstack.org/cactus URL to keep Cactus updated during the entire release cycle, but the automated builds go to /trunk. Versions of Doc --------------- For RST-based documentation, you can get to a point-release of a docs site by going to http://swift.openstack.org/1.1, for example. We'll keep doing that for ongoing releases. For Swift, we now have archived sites for the 1.4.0 and 1.4.1 release at swift.openstack.org/1.4.0 and swift.openstack.org/1.4.1. To make those archived sites, you can run a build on the Jenkins server at http://jenkins.openstack.org/view/Swift/job/swift-docs-archive/ and enter the version number and the Launchpad branch that you want to use to build the archived site. For DocBook documentation, the Continuous Integration work keeps docs building to docs.openstack.org/trunk.
Audiences and Targets
OpenStack has three main projects - Compute (nova), Object Storage (swift), and now an imaging service (glance). While the goals you'd achieve using each project vary, the three projects can also be used together. Those three projects have two basic audiences - developers and sysadmins (think operations or dev-ops). The RST-based documentation, because it automatically generates doc from docstrings in the code, is much more for a developer audience. There are two types of developers that the developer documentation serves - Python developers who want to work on OpenStack code, and web developers who work with the OpenStack API.
Workflow
The workflow for documentation matches the workflow for code - you download a branch, work on it locally, then commit the changes and propose a merge. Your changes are merged into the main, published doc base, and the doc is built to its varying outputs.
Detailed Workflow with Github and Gerrit
The page I always refer to for using Git and Gerrit for daily tasks is http://wiki.openstack.org/GerritWorkflow.
The workflow takes some startup work. First, you make a Launchpad account, and upload a public key. Then, you identify your Launchpad account to the git command line and away you go. You also need a Github account but the Launchpad account contains the signon and permissions information for the Gerrit workflow that we use for reviews.
Here's a sample for the documentation project specifically, once you get the Launchpad account set up.
Create the directory where you want to store the doc source files, then switch to it.
mkdir ~/src/docs cd ~/src/docs
Follow the steps in GerritWorkflow, using openstack-manuals as the project name for the Admin manuals, and project-api, such as compute-api, for the project name for API guides.
Now you can check out all the files for the admin doc project:
git clone git://github.com/openstack/openstack-manuals.git
Set up the Gerrit Change-Id hook, which is used for reviews, and run git review to run a script in the /tools directory which sets up the remote repository correctly:
cd $PROJECT git review
Now make sure you have the latest from Github (docs move more slowly than code, but this is a good practice).
git checkout master git pull origin master
Lastly, create a branch to do your work in that you'll do commits from:
git checkout -b TOPIC-BRANCH
Edit happily! You can use Oxygen since you're working on an open source project and we acknowledge their support.
When you're done with edits, if you've added any files do this in the working directory:
git add .
Next, you commit your changes with a message that'll be displayed in review.openstack.org, creating a change set:
git commit -a -m 'Here's what I did in this set of changes'
Next, push your changes for review with:
git review
Go to the review site itself to request a merge with the openstack-manuals project, at review.openstack.org. One of the core doc team members will review your edits and let you know if any changes are needed prior to merging them in.
To generate the PDF and webhelp within your local environment, install Maven. To run the pom file within the mvnbuild directory, which builds the Maven mojo, you run mvn install. Then, switch to the doc/ directory, and run mvn generate-sources using that pom.xml, to build the docs themselves.
You may need a modified settings.xml and if you already have M2_HOME set, you might see an error about "java.lang.ClassNotFoundException: org.codehaus.plexus.classworlds.launcher.Launcher" - just run unset M2_HOME.
Tools
Thanks to the generosity of Oxygen in supporting open source projects, you can edit DocBook XML within the Oxygen Author or Editor by downloading a copy of the software from http://www.oxygenxml.com/.
Translation
Translation efforts should occur either in the Launchpad Translations area (for strings in the code, error messages and the like) or on the wiki, which has translations enabled.
Figures
Here are some conventions for including figures and images in DocBook and RST documents.
In DocBook source, here is how you include images that have both a scalable-for-print-resolution in the PDF and an online-resolution for the HTML output. In this case the two types of images are SVG and PNG formats. The scale="60" attribute ensures that the image does not overlap print margins nor take up too much screen space.
<figure xml:id="CFinterfaces">
<title>Cloud Files System Interfaces</title>
<mediaobject>
<imageobject role="fo">
<imagedata scale="60" fileref="figures/CFinterfaces.svg"/>
</imageobject>
<imageobject role="html">
<imagedata scale="60" fileref="figures/CFinterfaces.png"/>
</imageobject>
</mediaobject>
</figure>
For DocBook, the convention is to use the /src/figures/ directory to store both the source image and any other formats of that same image. The pom.xml file copies the files in the /figures/ directory into the output directory required for HTML in the post processing section.
Also, when you add the image to the /src/figures directory, be sure to tell the source control system that you've added the image. For example, use "bzr add" to ensure the images get added to source control so the HTML and PDF output will be built correctly by the Jenkins continuous integration server.
For RST documents, this is the syntax for including an image in the output:
.. image:: /images/dating_service.png
The /images directory is relative to the doc/source directory, within /source. There's also an images_src directory in the doc/source directory that contains the source images so that they can be updated when needed.
For any figure you create, please also include the source files, even if the image was not created with open source tools, for maintenance purposes. While all OpenStack docs are created with open source in mind, including open-licensed fonts in the output, we are willing to allow non-open authoring or image creation tools if it's more efficient.
