Including in-code docs

Rendition of Karabo framework doc strings already works, this section describes how this can be achieved for doc strings in Karabo devices.

Steps required

An example Karabo devices including doc strings rendition is karaboDevices/puffin, viewing puffin files and performing the steps outlined below should get doc strings visible for your device project.

  • ensure that your conf.py includes the sphinx.ext.autodoc extension.
  • ensure that your sources are in the system path, e.g. by adding sys.path.append(‘../../src/’) to conf.py.
  • include in your index.rst’s toctree the name of the file, for puffin this is puffin_code.rst, defining which source files should be searched for doc strings to render. Puffin currently renders only strings from Puffin.py, which makes puffin_code very short and avoids any complication. If you need complication, then do it and update this documentation to share your knowledge. The directives in puffin_code are sufficient to render class and class method doc strings.
  • searching for doc strings in your project’s source requires importing Karabo framework files and these have to be made available to the virtual environment used by RTD. The Framework.git directive, see puffin’s requirements.rst below, must be inserted as-is into your project’s requirements.rst to make framework files available. Note that the robotDevice.git directive is required by puffin as Puffin.py inherits from karaboDevices/RobotDevice, this file must also be made available and your project may have similar dependencies.
sphinx==1.4.5
pint
git+https://git.xfel.eu/gitlab/Karabo/rtd-conf-py.git
slumber
breathe
numpy
matplotlib
git+https://github.com/enthought/traits.git
git+https://xfel.redmine:K9Sss5CmWtQ_nbx3gyt2@git.xfel.eu/gitlab/Karabo/Framework.git@master#egg=karabo&subdirectory=src/pythonKarabo
git+https://xfel.redmine:K9Sss5CmWtQ_nbx3gyt2@git.xfel.eu/gitlab/karaboDevices/robotDevice.git
lxml

It is not recommended to select the “Use system packages” option in (Admin > Advanced Settings), if a different version for one of the (internal) dependencies is required. e.g. sphinx 1.4.5 or sphinx-rtd-theme 0.4.3.

_images/use_system_packages.png