If you have any questions or would like help with the documentation, please contact the tech writer (Paulette) at: 1-216-433-8056 or paulette.j.ziegfeld@nasa.gov.
All documentation is located in the docs/ directory on your branch. There are separate directories for each user document. The following is a recent list of documents and their directory names in the Sphinx OpenMDAO Documentation project:
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.
1. In the following example, we will add text to an existing file (intro.rst) in the Developer’s Guide, so you need to go to that document’s directory on your branch:
cd /OpenMDAO/dev/<your_working_directory>/<branch_name>/docs
ls
cd dev-guide
ls
nedit intro.rst &
NEdit is an XWindows text editor. By using the “&” you’re telling it to run in the background.
See also
bzr status (Displays pending changes on your branch---additions, deletions,
modifications, and unknown files you did not add.)
bzr commit -m "<commit_message>" (Commits changes and allows you to add a commit message. Or, you may omit
"-m", and after pressing "Enter," type your comments using NEdit.)
nedit &
This will bring up an empty file. Add the desired text to the file and save it under a new name (e.g., new_file.rst) in the dev-guide directory.
Note
When you are using NEdit on a file, you can launch a spell-checking program (ispell) by typing Alt+b. When you are finished with ispell, the top of the file you are editing will say that the file has been modified, even if you made no spelling changes. So be sure to save your file.
nedit index.rst &
Add your file after the intro. The index would then look something like this:
=================
Developer's Guide
=================
.. toctree::
:maxdepth: 4
intro.rst
new_file.rst
linux
windows
working
testing
guidelines
distributions
As mentioned previously, it is not necessary to include the “.rst” suffix when adding a file to the index, but it does no harm.
If you need to create a new document within the OpenMDAO documentation, you must:
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 are to 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:
cd docs/
mkdir new-guide
cd new-guide
nedit &
This command brings up a blank document that you save under the desired name, such as file1.rst. Create as many files as you need, including an index.
nedit index.rst &
After adding the names of the files you created to the index.rst, your file might look something like this.
=========
New Guide
=========
.. toctree::
:maxdepth: 3
intro.rst
file1.rst
file2.rst
changes.rst
Note
Be sure to align the file names correctly or your file(s) will not display. You can always go to another index and copy its structure.
In general use overline and underline only for the title of a document (e.g., in the index file of a document). In other cases, it’s easier to use just underline. If you use both, the length of the lines must match or your build will fail. If you use just underline, and the line is shorter than the text you are underlining, you will get a warning, but it will build. If you use just underline and it is longer than the text, Sphinx doesn’t seem to mind.
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. Then use NEdit to add your new document (New Guide) to the the project’s index.rst:
cd ../ (Takes you up one level.)
nedit index.rst & (Opens the "index.rst" in NEdit.)
You should see something similar to this:
======================
OpenMDAO Documentation
======================
Contents:
.. toctree::
:maxdepth: 2
install-guide/index
user-guide/index
arch-doc/index
plugin-guide/index
dev-guide/index
srcdocs/index
licenses/index
quick-ref/index
Add new-guide/index in the desired location in the list of documents and save the file.
Your openmdao virtual development environment has scripts for building the sphinx documentation as well as viewing it.
cd /OpenMDAO/dev/<your_working_directory>/T<ticket#>-<branch_name>/devenv (Takes you to your virtual environment.)
bin/openmdao_build_docs (Builds the sphinx documentation)
bin/openmdao_docs (Displays the documentation in HTML using the default browser.)
The above example assumes that you have already created your virtual environment on your branch. If you haven’t, you need to run python2.6 go-openmdao-dev.py from the top directory in your branch repository. For more information, refer to the section on Building on Your Branch under Bazaar Commands. Note that to build the documents only, you may type bin/openmdao_build_docs.