Karabo-Related Documentation¶
Migrating Devices¶
For legacy devices and projects linked to Karabo, documentation migration needs to be performed. If you already have run sphinx-quickstart to start your device documentation, you do not have to do this again, but can instead adapt your conf.py to reflect the settings given for quickstart below.
If you first run `sphinx-quickstart, please make choices according to the following suggestions
Run sphinx-quickstart from within the ./doc folder:
Welcome to the Sphinx 1.2.3 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Enter the root path for documentation.
> Root path for the documentation [.]:
You should choose . as the root path, i.e. things will be mostly treated relative to your doc folder:
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
Please answer yes here. This way you can later add the build directory to a .gitignore file:
Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:
Please leave _ here to have things consistent:
The project name will occur in several places in the built documentation.
> Project name: XFEL ReadTheDocs
> Author name(s): S. Hauf
You should enter a human-readable and well suited project name here, frequently the device name, and the primary authors(s):
Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1. If you don't need this dual structure,
just set both to the same value.
> Project version: 1.0
> Project release [1.0]:
Give a meaningful project version and release number here.
The file name suffix for source files. Commonly, this is either “.txt” or “.rst”. Only files with this suffix are considered documents. > Source file suffix [.rst]:
Do not change this away from .rst:
One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:
Your master document always should be called index:
Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [n]: n
We do not create epub documentation, in fact it will fail on read the docs!
Please indicate if you want to use one of the following Sphinx extensions: > autodoc: automatically insert docstrings from modules (y/n) [n]: y
For anything containing code this is strongly recommended to be set to y:
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: n
This is optional, if you know how to use the doctest feature:
> intersphinx: link between Sphinx documentation of different projects
(y/n) [n]: n
The global configuration (see later) will take care of this:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
Allowing the .. todo:: directive is usually a good option:
> coverage: checks for documentation coverage (y/n) [n]:
Optionally, you can enable this feature:
> pngmath: include math, rendered as PNG images (y/n) [n]: n
Set this to n as we will be using mathjax.
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
Set this to y to enable math rendering:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: y
Set this to yes to enable conditional rendering:
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y
You can optionally set this to y:
A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: n
> Create Windows command file? (y/n) [y]: n
We do not need make files as we will host on RTD, but if you want to run local builds of your documentation, e.g. for testing, set “Create Makefile” to y:
Creating file ./source/conf.py.
Creating file ./source/index.rst.
Creating file ./Makefile.
Finished: An initial directory structure has been created.
You should now populate your master file ./source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
After you have created or edited your conf.py to reflect this settings, add the following import statement at the very beginning:
from rtd_conf import global_conf
and comment the lines:
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.mathjax',
'sphinx.ext.ifconfig',
'sphinx.ext.viewcode',
'sphinx.ext.graphviz',
]
if you do not need aditional extension (they are already globally configured), or change to:
extensions += ['other_extension']
if you need specific extensions.
Further comment:
intersphinx_mapping = {'http://docs.python.org/': None}
Finally, make sure to point your project configuration on RTD to the requirements.txt in your doc folder.