.. _including_incode_docs:

**********************
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 <https://git.xfel.eu/gitlab/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. 

.. code-block:: Python

    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
(:guilabel:`Admin` > :guilabel:`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.

.. image:: ./_images/use_system_packages.png