Merge pull request #324 from huard/ext_autodoc_options

Adds docstring and skiplines options to ext_autodoc

Author: ldesousa

docs/demobuffer.py

@@ -59,7 +59,7 @@ def __init__(self):
             title='Buffer',
             abstract='This process demonstrates, how to create any process in PyWPS environment',
             metadata=[Metadata('process metadata 1', 'http://example.org/1'),
-                      Metadata('process metadata 2', 'http://example.org/2')]
+                      Metadata('process metadata 2', 'http://example.org/2')],
             inputs=inputs,
             outputs=outputs,
             store_supported=True,

docs/external-tools.rst

@@ -47,7 +47,7 @@ ZOO-Project
 client (JavaScript) framework.
 
 QGIS WPS Client
---------------
+---------------
 
 The `QGIS WPS <https://plugins.qgis.org/plugins/wps/>`_ client provides a
 plugin with WPS support for the QGIS Desktop GIS.

docs/process.rst

@@ -389,17 +389,25 @@ To make the server visible from another computer, replace ``localhost`` with ``0
 Automated process documentation
 ===============================
 
-WPS :class:`Processes` can be automatically documented with `Sphinx`_ using the
+A :class:`Process` can be automatically documented with `Sphinx`_ using the
 `autoprocess` directive. The :class:`Process` object is instantiated and its
 content examined to create, behind the scenes, a docstring in the Numpy format. This
 lets developers embed the documentation directly in the code instead of having to
-describe each process in a separate file. For example::
+describe each process manually. For example::
 
   .. autoprocess:: pywps.tests.DocExampleProcess
+     :docstring:
+     :skiplines: 1
 
 would yield
 
 .. autoprocess:: pywps.tests.DocExampleProcess
+   :docstring:
+   :skiplines: 1
+
+The :option:`docstring` option fetches the :class:`Process` docstring and appends it after the
+Reference section. The first lines of this docstring can be skipped using the
+:option:`skiplines` option.
 
 To use the `autoprocess` directive, first add `'sphinx.ext.napoleon'` and
 `'pywps.ext_autodoc'` to the list of extensions in the Sphinx configuration file

pywps/ext_autodoc.py

@@ -1,8 +1,9 @@
 # -*- coding: utf-8 -*-
-from sphinx.ext.autodoc import ClassDocumenter
+from sphinx.ext.autodoc import ClassDocumenter, bool_option
 from sphinx.ext.napoleon.docstring import NumpyDocstring
 from sphinx.util.docstrings import prepare_docstring
 from sphinx.util import force_decode
+from docutils.parsers.rst import directives
 from pywps import Process
 from pywps.app.Common import Metadata
 
@@ -12,12 +13,26 @@ class ProcessDocumenter(ClassDocumenter):
     pywps.Process class.
 
     The Process description, its inputs and docputs are converted to a
-    numpy style docstring. Additional sections (Notes, References,
-    Examples, etc.) can be added in the Process subclass docstring.
+    numpy style docstring.
+
+    Additional sections (Notes, References, Examples, etc.) can be added
+    in the Process subclass docstring using the `docstring` option.
+    Additionally, docstring lines can be skipped using the `skiplines` option.
+
+    For, example, the following would append the SimpleProcess class docstring
+    to the published docs, skipping the first line.
+
+    .. autoprocess:: pywps.SimpleProcess
+       :docstring:
+       :skiplines: 1
+
     """
     directivetype = 'class'
     objtype = 'process'
     priority = ClassDocumenter.priority + 1
+    option_spec = {'skiplines':directives.nonnegative_int,
+                   'docstring':bool_option}
+    option_spec.update(ClassDocumenter.option_spec)
 
     @classmethod
     def can_document_member(cls, member, membername, isattr, parent):
@@ -96,7 +111,7 @@ class instance.
         for i in obj.outputs:
             doc.append("{} : {}".format(i.identifier, self.fmt_type(i)))
             doc.append("    {}".format(i.abstract or i.title))
-        doc.append('')
+        doc.extend(['',''])
 
         # Metadata
         hasref = False
@@ -129,6 +144,7 @@ def get_doc(self, encoding=None, ignore=1):
         from six import text_type
         # Get the class docstring. This is a copy of the ClassDocumenter.get_doc method. Using "super" does weird stuff.
         docstring = self.get_attr(self.object, '__doc__', None)
+
         # make sure we have Unicode docstrings, then sanitize and split
         # into lines
         if isinstance(docstring, text_type):
@@ -139,9 +155,9 @@ def get_doc(self, encoding=None, ignore=1):
         # Create the docstring by scraping info from the Process instance.
         pdocstrings = self.make_numpy_doc()
 
-        # Add the sections from the class itself.
-        if docstring is not None:
-            pdocstrings.extend(docstring)
+        if self.options.docstring and docstring is not None:
+            # Add the sections from the class docstring itself.
+            pdocstrings.extend(docstring[self.options.skiplines:])
 
         # Parse using the Numpy docstring format.
         docstrings = NumpyDocstring(pdocstrings, self.env.config, self.env.app, what='class', obj=self.object,

pywps/tests.py

@@ -19,11 +19,12 @@
 logging.disable(logging.CRITICAL)
 
 class DocExampleProcess(Process):
-    """
+    """This first line is going to be skipped by the :skiplines:1 option.
+
     Notes
     -----
 
-    This is additional documentation that can be added following the numpy docstring convention.
+    This is additional documentation that can be added following the Numpy docstring convention.
     """
 
     def __init__(self):