The OMS docs can be viewed online at http://docs.openmustardseed.org
All source code for these docs is available in this repository. If you would like to contribute updates or additions to the OMS documentation, please start by reviewing the information in the rest of this README.. it will help you get started.
Please see sources/contributing/documentation.rst
for details on installing
the dependencies for easily contributing updates to the OMS Documentation Project.
- Each of the .rst files under sources reflects a page on the documentation.
- Edit the
.rst
files with your favorite editor to your liking. - Run
make docs
to build the .rst into static .html with all CSS/js/etc properly linked and bundled together for you.. - The rendered, static website can now be found in the
_build
directory. - We've bundled an awesome development server, with an automated workflow, as part of the package. See the details in the contributing documentation noted above, the solution is based on grunt and node.js
- To preview what you have generated run
make server
and open http://localhost:9000/ in your favorite browser. - If it seems updates you have made are not taking effect, you may need to
remove the build directory with:
rm -rf _build
Please make note of the following conventions maintained throughout oms-docs:
- Wrap all lines at 80 characters, except where a long URL overflows
- Remove additional whitespace, at end of lines, tabs in empty lines, etc. With
vim this is as easy as running the command:
:%s/ $//
. Git will also flag lines ending with white space as RED within a diff, and can even be configured to ignore white space when making commits. - Convert tabs to spaces, it keeps everyone on the same page.
- Leave two empty lines between ending a section and starting a new one, as well as before starting a code block, and leave one empty line below a heading.
- Keep each commit focused on one type of contextual update, and linked to a ticket, just like with our source code.
- Follow existing/established conventions as much as possible, consistency makes it easy for others to get involved.
- Please refer to the section on ReST formatting and Sphinx directives included below.
- If you have many link references that originate from the same base URL, such
as many sections from the same RFC document, use the
extlinks
sphinx extension.
Note that the majority of the existing conventions carry over from our existing source code and established documentation practices within various open source communities. Additionally, many text editors will assist in wrapping at 80 characters, provide syntax highlighting, and ensuring tabs don't sneak in to replace spaces.
- http://sphinx-doc.org
- http://matplotlib.org/sampledoc/cheatsheet.html
- http://docutils.sourceforge.net/docs/user/rst/quickstart.html
Most of us learn this stuff by reading other source, so feel free to poke around what you see here, or in other projects as examples - django, docker, and many others have great docs rendered with sphinx.
A top-level section will need the following:
-
a new section entry in the Table of Contents (toctree) defined in
sources/toctree.rst
, such as:Get Started with OMS <get_started/index>
.Get Started with OMS
would be added to the navigation menu as a top-level section, and sphinx will expect to find anindex.rst
in this directory. -
a new directory created under
sources
, for examplesources/get_started
-
create the
index.rst
, eg:sources/get_started/index.rst
. If the new section will only have a single page, add all section content to this file. -
If the new section will have sub-sections, create each as another page within
sources/get_started/
and leavesources/get_started/index.rst
with just atoctree
directive like:.. toctree:: :maxdepth: 1 Initial Deployment <first_steps> Virtual Resource Controller <vrc> Trust Network <trust_network>
See the actual oms-docs source as existing examples.
Top-Level Heading
=================
Next Level Down
---------------
Then Still Further
~~~~~~~~~~~~~~~~~~
See also this bit about document and section titles and headers
To make links to specific places within the documentation, first create a link target:
.. _introduction:
Introduction to ...
===================
This is..
_introduction
is the link target and can then be referenced elsewhere in
the documentation with:
Start with an :ref:`Introduction to OMS <introduction>` ...
To make external links:
Some would say that `ZeroMQ Rocks!`_
.. _ZeroMQ Rocks!: http://zeromq.org
If embedding an image Trust_Framework_Features.png
into a page within the
introduction
section, you would first add the image to the directory:
sources/introduction/images/
.
Then, reference the image in your .rst document with:
.. image:: images/Trust_Framework_Features.png
:alt: Trusted Compute Framework Features
:align: center
Note that only the .. image: path/to/image.png
is required, the other
parameters to the image directive are optional.
Take note of how to format the text here with spacing above/below and indentation:
# a note (use when something is important)
.. note::
Include helpful notes to highlight important points the reader may
overlook while going through the docs.
# a warning (orange)
.. warning::
This will be deprecated in the next release.
# danger (red, use sparsely)
.. danger::
# these will not show up in the rendered doc unless configured to do so
.. todo::
We need to fix these things.
Include code examples with:
.. code-block:: bash
# here is my example
ls -alh /
And a python block may look like:
.. code-block:: python
print('hello world')
Code examples ought to have two spaces between the code example and the sections above and below it.
Tables require some-what specific formatting, but are very easy to write. There are two styles, detailed in this overview.
The file sources/tutorials/gps_demo.rst
has a good example of a large table
that is both readable and easy to maintain.
The primary requirements are that the directive lines (the ===) match up with the widths of text in each column.
This guide it a good place to start, but note that GitHub's flavor of Markdown has differences.
See GitHub's help doc for details on their version of Markdown.