****************************
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.