Documentation files to be linked under the docs/sphinx
directory of
http://github.com/openmicroscopy/openmicroscopy.
Getting started with Sphinx
Sphinx depends on the sphinx-build
Python script. As such, it can be
installed on any system with a working Python installation and PIP. On
Windows, make sure that the Scripts
directory under the Python installation
directory (e.g. C:\Python26\Scripts
) is configured in your PATH. On
OS X/Linux, sphinx-build
has to be accessible from the command line.
The Sphinx documentation system can be obtained by issuing:
pip install Sphinx
The structure of the documentation folder follows the Sphinx system guidelines. A quick overview:
- source *.txt files with reST markup live in the root of the folder and under subfolders,
- compiled output is placed in
_build
, - compiled visual themes are automatically placed in
_static
, - Sphinx configuration is held in
conf.py
, - goals for
make
andmake.bat
are held inMakefile
.
A reference of reStructuredText (reST) is available at http://thomas-cokelaer.info. It is recommended to familiarise oneself with the syntax outlined there.
A tutorial covering Sphinx, which enhances working with reST documents, can be found at http://sphinx.pocoo.org.
Building the documentation
To clean the build directory of any previous builds, use:
make clean
To build the documentation locally in the form of HTML pages, use:
make html
To check the links (internal and external) of the documentation, use:
make linkcheck
To list all targets of the sphinx builder, use:
make
The output should look something like:
Please use `make <target>' where <target> is one of
html to make standalone HTML files
dirhtml to make HTML files named index.html in directories
singlehtml to make a single large HTML file
pickle to make pickle files
json to make JSON files
htmlhelp to make HTML files and a HTML help project
qthelp to make HTML files and a qthelp project
devhelp to make HTML files and a Devhelp project
epub to make an epub
latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
latexpdf to make LaTeX files and run them through pdflatex
text to make text files
man to make manual pages
texinfo to make Texinfo files
info to make Texinfo files and run them through makeinfo
gettext to make PO message catalogs
changes to make an overview of all changed/added/deprecated items
linkcheck to check all external links for integrity
doctest to run all doctests embedded in the documentation (if
enabled)
Conventions used
Part of the conventions used here is based on work by Benoît Bryon.
File names
reST source file names should carry the txt
suffix and use lowercase
alphanumeric characters and the -
(minus) symbol.
Indentation
Most reST directives don't need indentation, unless contents or options have to be supplied. For consistency, please use 4 space indentation whenever needed. Do not use indentation for the start of directives (start them at the edge of the new line). Any content under a reST directive has to be indented the same way as the options.
Example:
.. toctree::
:maxdepth: 2
Some content here...
Line wrapping
reST source files should use 78 lines for wrapping text. Please consult the manual of your favourite text editor to see how to switch on text wrapping.
Blank lines
Two new lines should be put before top-lined, top-level section names, i.e. before H1 and H2. One new line in any other case.
Example:
###################
Document title (H1)
###################
Introduction text.
(blank)
(blank)
**************
A section (H2)
**************
Title headings
Every reST source file should begin with an H2 (level two) title. H1 titles are reserved for the index files (index.txt
).
Titles should be capitalised (see http://grammar.about.com for a discussion about capitalisation styles).
The following symbols should be used to create headings:
#
with top line*
with top line=
-
^
"
Example:
##################
H1: document title
##################
Introduction text.
*********
Sample H2
*********
Sample content.
**********
Another H2
**********
Sample H3
=========
Sample H4
---------
Sample H5
^^^^^^^^^
Sample H6
"""""""""
And some text.
Page labels and references
Every reST document should start with a label that matches the path and name of the document:
.. _path/name-of-the-page:
*****************
Title of the page
*****************
This label allows the page to be uniquely referenced in the rest of the
documentation. To do so, use the following syntax
:ref:`path/name-of-the-page`
or :ref:`link to my page <path/name-of-the-page>`
.
Images vs. Figures
reST allows for two types of image embedding: using the image
and figure
directive. It is recommended to use the latter, as legends and captions can be
added easier.
All images referenced in a reST document shall be placed in an images
folder
in the same directory as the reST file.
Substitutions, aliases and hyperlinks
reST allows for using substitutions in cases where a piece of markup is used more than once, e.g.
Please visit Python.org_
...
.. _Python.org: http://python.org
If a hyperlink appears only once, please use anonymous, "one-off" hyperlinks (two underscores):
`RFC 2396 <http://www.rfc-editor.org/rfc/rfc2396.txt>`__ and `RFC
2732 <http://www.rfc-editor.org/rfc/rfc2732.txt>`__ together
define the syntax of URIs.
Finally, please avoid using here
as the hyperlink name, as in:
(...) go `here <http://www.google.com>`_.
Common markups
- Notes should be formatted using the note directive:
.. note::
- Definition lists can be created and cross-referenced using the glossary
directive:
.. glossary::
- References to external documentation can be formatted using :
.. seealso::
- Menu selections should be marked using the appropriate role:
:menuselection:`Start --> Programs`
Global substitution
Some substitutions have been implemented using rst_epilog
in conf.py. They
can be used in all pages of the documentation.
Name | Path
-----------------+------------------------------------
|OmeroPy| | developers/Omero/Python
|OmeroCpp| | developers/Omero/Cpp
|OmeroJava| | developers/Omero/Java
|OmeroMatlab| | developers/Omero/Matlab
|OmeroCli| | developers/Omero/CommandLine
|OmeroApi| | developers/Omero/Modules/Api
|OmeroWeb| | developers/Omero/Web
|OmeroClients| | developers/Omero/GettingStarted
|OmeroInsight| | developers/Omero/Insight
|OmeroGrid| | developers/Omero/Grid
|OmeroSessions| | developers/Omero/Server/Sessions
|OmeroModel| | developers/Omero/Model
|ExtendingOmero| | developers/Server/ExtendingOmero
|BlitzGateway| | developers/Omero/Python/Gateway
For the most up-to-date list, please consult conf.py
(section rst_epilog
).
Common URLs
Some URLs are widely used across the OME documentation. Using the Sphinx
extlinks
extension, a dictionary of aliases to base URLs has been defined
for the following:
- Trac tickets:
:ticket:`3442`
, displayed as #3442 - Snapshots:
:snapshot:`omero/myzip.zip`
- Plone pages:
:plone:`Downloads <support/omero4/downloads>`
- DOIs:
:doi:`Dantas, et al., JCB <10.1083/jcb.201012093>`
- Github source code, e.g.
:source:`etc/omero.properties`
- OME Forums:
:forum:viewforum.php?f=3`
For the most up-to-date list, please consult conf.py
(section extlinks
).