Commit 45a9f78f authored by Manuel Günther's avatar Manuel Günther
Browse files

Removed dependency to numpydoc and adapted README accordingly.

parent 8ceba9f5
......@@ -45,7 +45,6 @@ so that you include the following::
setup_requires=[
'xbob.extension',
'numpydoc' # see below
],
...
......@@ -158,16 +157,6 @@ This documentation can be used after::
#include <xbob.extension/documentation.h>
The generated documentation relies on the ``numpydoc`` sphinx extension http://pypi.python.org/pypi/numpydoc, which is documented `here <http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_.
To use this package, please add the following lines in the ``conf.py`` file of your documentation (which is usually located in ``doc/conf.py``)::
extensions = [
...
'numpydoc',
]
# Removes some warnings, see: https://github.com/phn/pytpm/issues/3
numpydoc_show_class_members = False
Function documentation
======================
......@@ -197,16 +186,19 @@ Finally, when binding you function, you can use:
a) ``description.name()`` to get the name of the function
b) ``description.doc()`` to get the aligned documentation of the function, properly indented and broken at 80 characters (by default).
By default, this call will check that all parameters and return values are documented, and add a ``.. todo`` directive if not.
You can call ``description.doc(false)`` to disable the checks.
This call will check that all parameters and return values are documented, and add a ``.. todo`` directive if not.
Sphinx directives like ``.. note::``, ``.. warning::`` or ``.. math::`` will be automatically detected and aligned, when they are used as one-line directive, e.g.:
"(more text)\n.. note:: This is a note\n(more text)"
.. note::
Please assure that directives are surrounded by ``\n`` characters (see example above).
Otherwise, they will not be displayed correctly.
.. note::
The ``.. todo::`` directive seems not to like being broken at 80 characters.
If you want to use ``.. todo::``, please call ``description.doc(true, 10000)`` to avoid line breaking.
If you want to use ``.. todo::``, please call, e.g., ``description.doc(10000)`` to avoid line breaking.
Class documentation
......@@ -228,6 +220,9 @@ The shortest way to get a proper class documentation is::
.. note:: The second ``""`` in ``add_prototype`` prevents the output type (which otherwise defaults to ``"None"``) to be written.
Currently, the ClassDoc allows to highlight member functions or variables at the beginning of the class documentation.
This highlighting is still under development and might not work as expected.
Possible speed issues
=====================
......
......@@ -28,7 +28,6 @@ setup(
install_requires=[
'setuptools',
'numpydoc'
],
classifiers = [
......
......@@ -65,7 +65,7 @@ namespace xbob{
};
/**
* Use a static object of this class to generate a properly aligned and numpydoc compatible function documentation.
* Use a static object of this class to generate a properly aligned function documentation.
* Documentation generated by this class can be used for non-member functions as well as for member functions and constructors.
*/
class FunctionDoc {
......@@ -592,7 +592,6 @@ inline char* xbob::extension::VariableDoc::doc(
#ifdef XBOB_SHORT_DOCSTRINGS
return const_cast<char*>(variable_description.c_str());
#else
// The numpydoc standard does not use variable types, so I came up with my own way of it
description = _align("*" + variable_type + "* <-- " + variable_description, 0, alignment);
return const_cast<char*>(description.c_str());
#endif // XBOB_SHORT_DOCSTRINGS
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment