Updating OpenMDAO Documents

You must update the OpenMDAO documentation any time you make a change that will affect users or developers.

All documentation is located in the docs/ directory on your branch. There are separate directories for each user document, such as user-guide, plugin-guide, srcdocs.

There are several other files and subdirectories in this directory (e.g., images, generated_images, config.py, Makefile, _build, _static) that you can ignore for now. User document files (e.g., index.rst, glossary.rst) are in reStructuredText (reST) markup language and always end in .rst. The subdirectories for the documents in many cases contain a hyphen in their name.

Updating an Existing Document

  • If you are merely changing a file in an existing document, (e.g., intro.rst in the Developer’s Guide), from top level of your branch, go to docs/dev-guide.

  • Use the editor of your choice to open intro.rst and make your changes.

  • Save the file and then commit your changes.

    Your doc changes will be incorporated when your branch is merged.

If you need to create a new file in an existing document (e.g., the Developer’s Guide), do the following:

  • Create a file in the dev-guide directory with a text editor of your choice and save it with an appropriate name, in this example, new_file.rst.

  • You must add the name of the new file to the index.rst in the same directory so that Sphinx knows to grab it and where to place it in the document. Open index.rst and add your file (in the example below, after intro.rst).

    The index should then look similar to this:

Developer's Guide

.. toctree::
   :maxdepth: 2


It is not necessary to include the .rst suffix when adding a file to the index, but it does no harm. Save the file.

  • Be sure to use the bzr add command to add the file to the repository. Also, remember to commit your changes.

Creating a New Document

There is a main index.rst file for the entire OpenMDAO documentation project. Additionally, each document subdirectory has its own index.rst that lists the files in its document (in the order they should appear). For example, if you are at the top level on your branch and want to create a new document called New Guide in our OpenMDAO documentation, you would do the following:

  • Create a new subdirectory in the docs directory
  • Create your new files in that subdirectory, including an index.rst
  • Add the new file(s) to your index
  • Add the document (new subdirectory) to the project index, so Sphinx knows about it
  • Add the new directory and files to the bzr repository

See the example that follows.

  • From the top level branch directory, create the new subdirectory and then go there:

    cd docs/
    mkdir  new-guide
    cd new-guide
  • Create your files using an editor of your choice, e.g., file1.rst and file2.rst.

  • Add the file names to your index. After adding the names of the files you created to the index.rst, your file might look something like this.

New Guide

.. toctree::
   :maxdepth: 2



Be sure to align the file names correctly or your file(s) will not display.

  • Now that you have a subdirectory with files and have added the file names to the index.rst for your document, you must add the document to the index.rst for the entire OpenMDAO documentation project.

    Remember, you are in new-guide directory. After saving your file, go up one level to the docs directory. You should see something similar to this:

OpenMDAO Documentation


.. toctree::
   :maxdepth: 1


Use your text editor to add new-guide/index to the desired location in the project’s index.rst and then save the file.

  • Use bzr add to add the new directory and files to the repository. Remember to commit your changes when ready.

Building and Displaying Documents

Your openmdao virtual development environment has scripts for building and displaying the Sphinx documentation. The following example assumes that you have already created your virtual environment on your branch. If you haven’t, you must run python2.6 go-openmdao-dev.py from the top directory in your branch repository.

cd devenv                  (Takes you to your dev environment)
openmdao_build_docs        (Builds the Sphinx documentation)
openmdao_docs              (Displays the documentation in HTML using the default browser)


If you have a preexisting devenv directory in your branch directory, you should delete it before running the go-openmdao-dev.py script.

OpenMDAO Home

Table Of Contents

Previous topic

Updating OpenMDAO Documentation

Next topic

Sphinx and reStructuredText

This Page