davemds pushed a commit to branch master.
http://git.enlightenment.org/bindings/python/python-efl.git/commit/?id=b84c109fefb81b6a502d1a9380b0e2d2b9dc1c6c
commit b84c109fefb81b6a502d1a9380b0e2d2b9dc1c6c
Author: davemds <d...@gurumeditation.it>
Date: Sun Apr 6 16:17:27 2014 +0200
doc: automatically show parameters in functions and methods documentation
This require the Cython "embedsignature" directive, that automatically add
the signature in the first line of the docstring.
Then the Sphinx Autodoc module parse the docstring and extract the
signature.
Signature is also cleaned using the 'autodoc-process-signature' callback to
remove the 'self' param and all the cython params type,
---
doc/conf.py | 44 ++++++++++++++++++++++++++++++++++----------
setup.py | 1 +
2 files changed, 35 insertions(+), 10 deletions(-)
diff --git a/doc/conf.py b/doc/conf.py
index f9be31b..7127244 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -24,13 +24,13 @@ d = "lib.%s-%s-%d.%d" % (
sys.version_info[1]
)
sys.path.insert(0, os.path.abspath("../build/"+d))
-
#sys.path.insert(0, os.path.abspath('../build/lib.linux-i686-3.2'))
+
# -- General configuration
-----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+needs_sphinx = '1.1'
# Add any Sphinx extension module names here, as strings. They can be
extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
@@ -46,7 +46,8 @@ except ImportError:
else:
extensions.append('sphinx.ext.inheritance_diagram')
graphviz_output_format = "svg" # png (default) or svg
- graphviz_dot_args = ["-Gbgcolor=transparent", "-Ncolor=#4399FF",
"-Nfontcolor=white", "-Ecolor=blue"]
+ graphviz_dot_args = ["-Gbgcolor=transparent", "-Ncolor=#4399FF",
+ "-Nfontcolor=white", "-Ecolor=blue"]
try:
import sphinxcontrib.youtube
@@ -55,13 +56,6 @@ except ImportError:
else:
extensions.append('sphinxcontrib.youtube')
-autodoc_default_flags = [
- 'members',
- #'inherited-members',
- 'show-inheritance'
-]
-autoclass_content = "both"
-autodoc_docstring_signature = True
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -148,6 +142,36 @@ pygments_style = 'sphinx'
# ('py:obj', 'datetime.date'),
# ]
+
+# -- Autodoc configuration
-----------------------------------------------------
+
+autodoc_default_flags = [
+ 'members',
+ 'show-inheritance',
+ # 'inherited-members',
+ # 'undoc-members',
+]
+autoclass_content = "both"
+autodoc_docstring_signature = True
+# autodoc_member_order = "bysource"
+
+def setup(app):
+ app.connect('autodoc-process-signature', autodoc_process_signature)
+
+def autodoc_process_signature(app, what, name, obj, options, signature,
return_annotation):
+ """Cleanup params: remove the 'self' param and all the cython types"""
+
+ if what not in ('function', 'method'):
+ return
+
+ params = list()
+ for param in (p.strip() for p in signature[1:-1].split(',')):
+ if param != 'self':
+ params.append(param.rpartition(' ')[2])
+
+ return ('(%s)' % ', '.join(params), return_annotation)
+
+
# -- Options for HTML output
---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
diff --git a/setup.py b/setup.py
index 196301d..229b59c 100755
--- a/setup.py
+++ b/setup.py
@@ -359,6 +359,7 @@ setup(
compiler_directives={
"c_string_type": "unicode",
"c_string_encoding": "utf-8",
+ "embedsignature": True,
}
),
)
--
