Jump to: navigation, search

Difference between revisions of "Documentation/HowTo"

(Replaced content with "Read the new content in the [http://docs.openstack.org/contributor-guide/index.html Documentation Contributor Guide]. {{OpenStack_Documentation_Navbar}} ---- Category:...")
(248 intermediate revisions by 33 users not shown)
Line 1: Line 1:
= How To Work on OpenStack Documentation =
Read the new content in the [http://docs.openstack.org/contributor-guide/index.html Documentation Contributor Guide].
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. [[AnneGentle|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 and Content Overview ==
The tool used for the documentation depends on the audience for the docs.
We use DocBook to create OpenStack's web documentation for deployers, admins, and CLI and API users. We use RST files stored in source code for developer docs. RST is [http://docutils.sourceforge.net/docs/user/rst/quickref.html ReStructured Text], it has a similar text-based markup as wikitext. We used an online collaboration tool called Booktype for the Operations Manual during a book sprint, located at http://openstack.booktype.pro/.
To work on the RST source files, find the /doc/source/ directory in a given OpenStack project to work on the source .rst files. These are built to http://docs.openstack.org/developer/<project>, for example, http://docs.openstack.org/developer/nova.
To work on the DocBook source files for admin guides, a working project exists in Github in the http://github.com/openstack/openstack-manuals project since DocBook documentation encompasses all OpenStack projects.
To work on the DocBook and WADL source files for http://api.openstack.org, look for the openstack/api-site project on Github and use the same [[GerritWorkflow]].
All API spec documentation that builds to http://docs.openstack.org/api is housed in image-api, identity-api, compute-api, netconn-api, and object-api repositories. Changes to these are approved by the core development team because they are specifications.
Here's a walk through of the contribution process showing how to pick up a doc bug and submit a patch for it.
== First-time Contributors ==
First, thanks for contributing to docs! Secondly, you're just like a developer. Here are the overall steps to get started.
1. '''Sign the [[CLA]]:''' Every developer and contributor needs to sign the Individual Contributor License agreement.
2. '''Create a Launchpad account:''' Visit https://login.launchpad.net/+new_account After you create this account, the followup page is slightly confusing. It doesn't tell you that you are done. (It gives you the opportunity to change your password, but you do not have to.) 
3. Add at least one SSH key to your account profile.  To do this, follow the instructions on https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair.
4. Create a Github account and add SSH keys to your account profile (same one as used in Launchpad, they must match). If this is your first time setting up git and Github, be sure to run these steps in a Terminal window:
$ git config --global user.name "Firstname Lastname"
$ git config --global user.email "your_email@youremail.com"
5. Install git-review. If pip is not already installed, use "sudo easy_install pip" to install it on a Mac or Ubuntu
sudo pip install git-review
6. Clone the openstack-manuals repository with:
git clone http://github.com/openstack/openstack-manuals.git
cd openstack-manuals
7. Enter your Launchpad account information after testing for ssh key setup with git review -s.
git review -s
'''Note''': If you see any "Permission denied" errors at this step, go to [http://review.openstack.org review.openstack.org], log in, and check through all the items in your Settings link to ensure that everything matches. You may need to enter your SSH key in the Gerrit site (review.openstack.org).
'''Note''': If you get the error "We don't know where your gerrit is.", you will need to add a new git remote. The url should be in the error message. Copy that and create the new remote with this command:
git remote add gerrit ssh://<username>@review.openstack.org:29418/openstack/openstack-manuals.git
8. Now you can work on the openstack-manuals locally and submit patches. Refer to the [[GerritWorkflow]] steps to contribute your changes.
That should get you started contributing to docs just like code. Read more for the details of what types of documentation go where.
== Building Output Locally ==
The [https://github.com/rackspace/clouddocs-maven-plugin  Clouddocs Maven Plugin] and a pom.xml configuration file in combination enable the builds to docs.openstack.org and api.openstack.org.
Here are the quick steps for getting started on the openstack-manuals project once you have acquired the source files:
1. First install the Apache Maven project, and Git
With Macports:
sudo port install maven3
#Install Git by referring to: https://help.github.com/articles/set-up-git#platform-mac
With Homebrew:
brew install maven
#Install Git by referring to: https://help.github.com/articles/set-up-git#platform-mac
on Ubuntu:
sudo apt-get install maven git
on Fedora:
sudo yum install maven git
2. Get a copy of the docs source files.
git clone https://github.com/openstack/openstack-manuals.git
The different manuals are in subdirectories of the
openstack-manuals/doc/src/docbkx directory.
For example, the root directory of the OpenStack Compute Administration Guide
is openstack-manuals/doc/src/docbkx/openstack-compute-admin.
To build a specific guide, look for a pom.xml file within a subdirectory, switch to that directory,
then run the mvn command in that directory. For example::
cd openstack-manuals/doc/src/docbkx/openstack-compute-admin
mvn clean generate-sources
The generated PDF documentation file is::
The root of the generated HTML documentation is::
For the install guides, there's a section in the pom.xml that tells the build whether to create the ubuntu version of the guide or the RHEL/CentOS/Fedora version of the guide. Right now, the master branch pom.xml file defaults to ubuntu with this section:
<!-- This is set by Jenkins according to the branch. -->
        <!-- This is set by Jenkins to run twice for each similar operating system group -->
If you want to build the RHEL/CentOS/Fedora version of the install guide, change that section to this instead:
<!-- This is set by Jenkins according to the branch. -->
        <!-- This is set by Jenkins to run twice for each similar operating system group -->
And then re-run the '''mvn clean generate-sources''' command to get the RHEL output.
The RST source is built into html using Sphinx so that it gets displayed on [http://docs.openstack.org/developer/nova Nova developer site], [http://docs.openstack.org/developer/swift/ Swift developer site], [http://docs.openstack.org/developer/glance/ Glance developer site], and [http://docs.openstack.org/developer/keystone/ Keystone developer site].
The DocBook source is built into html (webhelp) and PDF using XSLT transforms included with the DocBook project.
== Reviewing Documentation ==
To see what documentation changes are ready for review, go to http://review.openstack.org and search for project:openstack/openstack-manuals. Or go to [https://review.openstack.org/#/q/status:open+project:openstack/openstack-manuals,n,z  this page with the search already completed].
Click a patch set.
Click a file that has changed to view the changes side by side.
Click the Review button and vote, then enter any comments about your review.
Usually small changes are easy to review online. For larger changes, you want to bring the changes locally to ensure they build correctly and to review the output as well as the source. Here's how:
git review -d <nnnnn>
Where the value of nnnnn comes from the review.openstack.org URL, such as 11215 from the URL https://review.openstack.org/#/c/11215/.
The git review tool creates a new branch locally with the patch set. Change directories to the one containing the pom.xml for the deliverable you want to build and run:
mvn clean generate-sources
Review the source and the output, and feel free to edit and patch it as well. When you're sure the build and output are good, run:
git commit -a --amend
When the editor opens, write a new line telling the reason for the patch set.
Enter colon + w + q to save and exit the editor with the amended commit message.
Next, run:
git review
To send your patch to patch the existing review.
== What Docs Go Where? ==
{| border="1" cellpadding="2" cellspacing="0"
|<tablebgcolor="#cccccc"  >|wiki
| Use for project docs, blueprint specs.
| Use for Python developer documentation and quick starts.
| The audience is any project team member of OpenStack.
| The audience is Python developers who want to work on the project.
| Output is per-page at wiki.openstack.org
| Output goes to docs.openstack.org/developer/nova.
=== wiki.openstack.org  (wikitext or RST) ===
The OpenStack wiki contains project docs, specs for blueprints, and meeting information and minutes. 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).
=== docs.openstack.org/developer/<projectname> (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 5) ===
As mentioned above, the source for this site is housed in Github in the http://github.com/openstack/openstack-manuals project, the Launchpad page for this project is https://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/src/docbkx/$BOOK contains the DocBook XML source files and images
When editing DocBook documentation, please adhere to the DocBook 5 syntax. If you've used DocBook version 4 or earlier before, and you're not familiar with the changes that DocBook saw in V5.0, the [http://docbook.org/docs/howto/ Transition Guide] is a helpful read.
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. Here is a copy of a working settings.xml file:
        <activeProfile>Rackspace Cloud Research</activeProfile>
            <id>Rackspace Cloud Research</id>
== 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.4, 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 in openstack-manuals, we have different branches available for authoring - the StableBranch for prior releases and master or HEAD which corresponds to docs.openstack.org/trunk. The Continuous Integration work keeps docs building to docs.openstack.org/trunk and docs.openstack.org/{essex|folsom} based on the branch they are checked into.
To work on edits that affect only Folsom, you need to:
* install and use the git-review tool, read more about it here: https://github.com/openstack-ci/git-review.
* follow the [[GerritWorkflow|normal Gerrit workflow]] with these two changes:
** - instead of 'git checkout master' use '''git checkout gerrit/stable/folsom''' - instead of 'git review' use '''git review gerrit/stable/folsom'''
* be very considerate of what you are documenting specifically for the stable release and why. If it applies to the stable release and ongoing releases, you have to make your edits twice.
* note that the reviewers with +2 permissions for the stable release branch are doc-core members and the stable maintenance team.
At release time, have one doc contributor (or the doc lead) follow the [[Documentation/Release]] instructions to make a release branch.
== Doc Comments Guidelines ==
A released set of documents has Disqus comments enabled, but the docs.openstack.org/trunk site does not have Disqus comments enabled. The Disqus identifiers are mapped to particular documents. If you would like to be a moderator on particular Disqus topics, first sign up for Disqus, then send an email to openstack-doc@lists.openstack.org with your Disqus email address and which topics from the list below you would like to moderate and respond to questions.
* Keystone Developer Guide (os-identitydevguide)
* OpenStack API Quick Start (os-apiquickstart)
* OpenStack Command Line Interface Clients Guide (os-cliguide)
* OpenStack High Availability Guide (openstack-ha-guide)
* OpenStack Install and Deploy Manual - Fedora/RHEL/CentOS (os-install-yum)
* OpenStack Install and Deploy Manual - Ubuntu/Debian (os-install-apt)
* OpenStack Compute API Programmer Guide (os-computeapiprogrammer)
* OpenStack-quantum (os-quantum-guides)
* OpenStack Documentation includes Compute Admin Guide, Object Storage admin guide, Compute API v2, Object Storage API v1.0 (openstackdocs)
Note: We should probably have separate Disqus topics for each book. Plus the image API doesn't have Disqus comments enabled currently. Tracking with this doc bug: [https://bugs.launchpad.net/openstack-api-site/+bug/1067208 1067208]
When a doc comment comes in that shows there's a doc bug, log the doc bug, then paste the link to the bug back into the comment thread so the reporter can track. Then once the bug is fixed, indicate that in the comment also, closing the loop on the doc bug (that was basically submitted through the commenting system.)
== Doc Bug Triaging Guidelines ==
Doc bugs are logged and triaged at http://bugs.launchpad.net/openstack-manuals. You can see how well we're doing with bugs [http://webnumbr.com/untouched-bugs-in-openstack-manuals- at this webnumbr]. Here are some definitions for Status and Importance so you can triage incoming doc bugs.
New - Recently logged by a non-triaging person
Incomplete - Needs additional information before it can be triaged
Opinion - (not sure what to do with this one)
Invalid - Not an issue for docs
Won't Fix - Doc fixes won't fix the issue
Confirmed - Acknowledged that it's a doc bug
Triaged - Comments in the bug indicate its scope and amount of work to be done
In Progress - Someone is working on it
Fix Committed - A fix is in the repository; Gerrit sets this automatically
Fix Released - A fix is published to the site; would like the CI team to set this automatically, bug filed [https://bugs.launchpad.net/openstack-ci/+bug/943413 bug 943413]
Critical - data will be lost if this bug stays in; or it's so bad that we're better off fixing it than dealing with all the incoming questions about it. Also items on the website itself that prevent access are Critical doc bugs.
High - Definitely need docs about this or a fix to current docs; docs are incomplete without this. Work on these first if possible.
Medium - Need docs about this within a six-month release timeframe.
Low - Docs are fine without this but could be enhanced by fixing this bug.
Wishlist - Would like this doc task done "some day" Would prefer to use this for "tasks" instead of "bugs" - mark a bug as low rather than putting it on the wishlist. When something is wrong with the doc, mark it as Low rather than Wishlist.
Undecided - Recently logged by a non-triaging person or requires more research before deciding its importance.
== 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. Members of the openstack-doc-core team and others review your changes and after receiving enough +1 votes, an openstack-doc-core member can push +1 Approved. Once approved, your changes are merged into the main, published doc base, and the doc is built to its varying outputs with the Jenkins server.
=== Using the DocImpact Flag in a Commit Message ===
In any OpenStack project, you can add a DocImpact flag in a commit message to send an email to the openstack-docs mailing list notifying them of the possible impact to documentation due to the patch. If your commit could have an impact on documentation - be it an added/altered/removed commandline option, a deprecated or new feature, a caveat, if you've written docs in the patch, or if you're just not sure, just add "DocImpact" to a line in your commit message.
This sends the doc team an email so we can triage. It doesn't guarantee docs will
be written, but at least it gives us visibility of the changes. You can also use it as a reminder to yourself to write docs for the feature later, that's okay too. With over 500 contributors to the code base and a handful of writers, there's always doc work to be done.
If you are a doc contributor, these are the steps we take once a DocImpact notification comes to the list.
1. Create a new doc bug in either openstack-manuals or openstack-api-site. In the bug:
* In the title, put "grizzly" or "havana" depending on the release the patch will land in.
* Copy and paste the review.openstack.org link in the bug description.
* Describe the documentation that is affected if the code patch lands in the bug description.
* Keep the doc bug set to "New" until the code patch is merged.
2. Continue to check on the patch and change the status to "Confirmed" once merged.
3. Use the information in the Doc Bug Triaging Guidelines section to set priority once it lands.
=== 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 to get the accounts you need. 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. 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 your Launchpad and Github accounts 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 a doc repo to get the source:
As an example, here's how you check out all the files for the admin docs in openstack-manuals:
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:
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 [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:
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 'bug xxxxxxx 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 see the review votes for 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.
=== How to amend a review-in-progress ===
Within the repository for which you have a patch, do these steps:
git review -d 5829
where 5829 is the four-digit identifier found in the review.openstack.org URL for the patch set.
A new branch is created and checked out that you'll work within.
Then make your edits in the new branch that is created. Once edits are complete, do:
git commit -a --amend
and in the vi editor, add more lines to your commit message to explain the reasons for the patch set.
Press Esc :wq to save the message and quit the VI editor.
Then do: git review -v
=== How to a cherry-pick a change to a stable branch ===
Let's say a docfix was submitted to the master openstack-manuals branch, and you want this change to be reflected in the Folsom documentation, which has already closed. You can cherry pick the change and submit it.
Let's say we want to cherry-pick bug/948242 (review 7480) into folsom.
0. Make sure your repository is up to date:
git fetch origin
1. Create a topic branch by branching from folsom:
git checkout -b folsom-bug/948242 remotes/origin/stable/folsom
2. On the Gerrit web page that contains the review you want to backport, click "cherry-pick" (It's under Patch Set N, in the Download row), copy the text, and then paste it into your terminal. For example, for review 7480, it looks like this:
git fetch https://review.openstack.org/openstack/openstack-manuals refs/changes/80/7480/2 && git cherry-pick FETCH_HEAD
3. Amend the commit log (Add something like ''Cherry picked from http://review.openstack.org/7480'') and submit for review:
git commit --amend
git review stable/folsom
== Editor Options ==
We encourage the use of Oxygen for editing XML - it offers consistency in white space which makes diffs in review.openstack.org easier. If you prefer a text-based editor but with validation, you can use Emacs. Here are some great resources on DocBook and Emacs' NXML mode:
* http://paul.frields.org/2011/02/09/xml-editing-with-emacs/
* https://fedoraproject.org/wiki/How_to_use_Emacs_for_XML_editing
* http://infohost.nmt.edu/tcc/help/pubs/nxml/
If you prefer vi, there are ways to make DocBook editing easier:
* https://fedoraproject.org/wiki/Editing_DocBook_with_Vi
=== Oxygen XML Acknowledgment ===
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/. Send an email to anne at openstack dot org to request the license extension beyond the 30-day trial.
=== Oxygen and the Rackbook Framework ===
Thanks to Rackspace maintaining Oxygen tools that make authoring DocBook and WADL, we can offer a Rackbook framework. Download the [http://feline.thingbag.net/oxygen-frameworks.zip oxygen-frameworks.zip] file. Next, download the following file to  your system:
[http://wiki.openstack.org/Documentation/HowTo?action=AttachFile&do=get&target=defaults.xpr defaults.xpr]. Extract the oxygen-frameworks.zip file to ~/Library/Preferences (i.e. so you end up with /Users/your.username/Library/Preferences/com.oxygenxml.author). In Oxygen, go to Options->Import Global Options. Navigate to the downloaded defaults.xpr file and click Open.You should see a new bar of buttons and a Rackbook menu item.
You can also run directly from http://docs.rackspace.com/oxygen/ with a license.
== Translation ==
Translation efforts occur in the Transifex web site. Review the [[Documentation/Translation]] for all the technical details.
== Markup Conventions ==
Refer to [[Documentation/Conventions]] for markup information.
=== Figures ===
Conventions for including figures and images in DocBook have been moved to the [[Documentation/Conventions#Embedding_images|Conventions page]]
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.
== How to create PDF links on webhelp landing pages ==
You need these items to make the PDF link work:
<?rax pdf.url="../os-install-guide-trunk.pdf"?> above the title element in the book file, where the filename and path point to the PDF file name.
in the pom.xml file.
And at least <version>1.0.9</version>
in the pom.xml file for the plugin com.rackspace.cloud.api.
== How to use the Booktype tool ==
Just some notes after the book sprint for the Operations Guide.
Download Chrome 26 and enable Experimental webkit from chrome://flags.
Do the publishing steps within Chrome.
Make an account.
_edit -- for editing
_full -- for seeing the whole book
mobi: use the Publish tab on booktype
epub: use the openstack.booksprints.net/wizard1.html page
PDF: print from the generated wizard1.html page, delete half the pages
cover: from OpenStack Foundation, back cover text on the etherpad
css: at the bottom of https://etherpad.openstack.org/EssexOperationsGuide

Latest revision as of 19:25, 26 October 2015

Read the new content in the Documentation Contributor Guide.