Jump to: navigation, search

Difference between revisions of "Documentation/HowTo"

(Adding detailed bzr steps)
Line 55: Line 55:
  
 
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 BZR and Launchpad ===
 +
 +
The page I always refer to for using BZR and Launchpad for daily tasks is
 +
http://wiki.openstack.org/LifeWithBzrAndLaunchpad
 +
 +
Launchpad takes some startup work. First, you make an account, and upload a public key. Then, you identify your Launchpad account to the bzr command line and away you go.
 +
 +
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.
 +
 +
 +
<pre><nowiki>
 +
mkdir ~/src/openstack-manuals
 +
 +
cd ~/src/openstack-manuals
 +
</nowiki></pre>
 +
 +
 +
Identify yourself to bzr:
 +
 +
<pre><nowiki>
 +
bzr whoami "Mark Pace <pace@jolokianetworks.com>"
 +
</nowiki></pre>
 +
 +
bzr lp-login markpace
 +
 +
Next, initialize the repository as the /openstack-manuals/ directory for that project.
 +
 +
<pre><nowiki>
 +
bzr init-repo .
 +
</nowiki></pre>
 +
 +
 +
Now you can check out all the files for the doc project:
 +
 +
<pre><nowiki>
 +
bzr branch lp:openstack-manuals trunk
 +
</nowiki></pre>
 +
 +
 +
Next, branch trunk to another working branch:
 +
 +
<pre><nowiki>
 +
bzr branch trunk working
 +
</nowiki></pre>
 +
 +
Switch to the working directory and edit files in the working directory. When you're done, if you've added any files do this in the working directory:
 +
 +
<pre><nowiki>
 +
bzr add
 +
</nowiki></pre>
 +
 +
Next, you commit your changes with a message that'll be displayed in Launchpad, creating a change set:
 +
 +
<pre><nowiki>
 +
bzr commit -m 'Here's what I did in this set of changes'
 +
</nowiki></pre>
 +
 +
Next, push your changes to Launchpad with:
 +
 +
<pre><nowiki>
 +
bzr push lp:~markpace/openstack-manuals/working
 +
</nowiki></pre>
 +
 +
Go to the Launchpad site itself to request a merge with the openstack-manuals project, such as https://code.launchpad.net/~markpace/openstack-manuals/working. Click "Propose for Merging" on that page. This sends an email to the project owners, they review the changes, and then you'll see any comments the editors have for you. If you need to make any changes, go to the files in your working directory, and repeat the commit and push steps after making edits.
  
 
== Translation ==
 
== Translation ==

Revision as of 14:14, 28 March 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 create an account on wiki.openstack.org, create a new page, and start editing.

Editing RST or DocBook has a few more steps. If you're on Mac or Linux (Ubuntu for example), you create a Launchpad account, install Bazaar (see http://wiki.openstack.org/LifeWithBzrAndLaunchpad) and get the code so you can work on .rst or .xml files in 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.

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 new project, http://launchpad.net/openstack-manuals. It's not yet part of the build process and is manually built right now. (I'll work with Monty and/or Soren to automate builds, detailed email to them to follow.) You can build the output if you want or just submit changes to the source XML.

 * doc/source/docbkx contains the DocBook XML source files and images
 * doc/build/docbook-xsl-1.76.1/webhelp contains the OpenStack transforms to create the HTML using an ant build
 * doc/buildpdf/rc-maven-cloud-docs contains the OpenStack transforms and Maven mojo to create the PDFs
 * doc/staging/ contains the files that are copied to docs.openstack.org

I plan to create a docs.openstack.org/current URL to keep updated during the entire release cycle. 

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.


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.

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 BZR and Launchpad

The page I always refer to for using BZR and Launchpad for daily tasks is http://wiki.openstack.org/LifeWithBzrAndLaunchpad

Launchpad takes some startup work. First, you make an account, and upload a public key. Then, you identify your Launchpad account to the bzr command line and away you go.

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/openstack-manuals

cd ~/src/openstack-manuals


Identify yourself to bzr: 

bzr whoami "Mark Pace <pace@jolokianetworks.com>"

bzr lp-login markpace

Next, initialize the repository as the /openstack-manuals/ directory for that project. 

bzr init-repo .


Now you can check out all the files for the doc project: 

bzr branch lp:openstack-manuals trunk


Next, branch trunk to another working branch: 

bzr branch trunk working

Switch to the working directory and edit files in the working directory. When you're done, if you've added any files do this in the working directory: 

bzr add

Next, you commit your changes with a message that'll be displayed in Launchpad, creating a change set: 

bzr commit -m 'Here's what I did in this set of changes'

Next, push your changes to Launchpad with: 

bzr push lp:~markpace/openstack-manuals/working

Go to the Launchpad site itself to request a merge with the openstack-manuals project, such as https://code.launchpad.net/~markpace/openstack-manuals/working. Click "Propose for Merging" on that page. This sends an email to the project owners, they review the changes, and then you'll see any comments the editors have for you. If you need to make any changes, go to the files in your working directory, and repeat the commit and push steps after making edits.

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.

Detailed Environment Setup

Environment: Ubuntu 10.04 or 10.10 or Mac OS X 10.6

To build HTML output:

Prereqs: Install ant 1.8 or higher (with a dependency on 1.8.0 and adding the following jars to your CLASSPATH:

You could get xercesImpl.jar and xml-apis.jar from a pre-1.8.1 distribution of Ant (from the lib dir)

Install docbook-xsl-1.76.1

Retrieved from "https://wiki.openstack.org/w/index.php?title=Documentation/HowTo&oldid=4457"