hacks for Cython extensions (issue #49), fixes for python 2.7, use setuptools-scm

.gitignore

@@ -3,6 +3,7 @@ tags
 build
 MANIFEST
 dist
+pdoc/_version.py
 *.egg-info
 *.pyc
 *.pyo

longdesc.rst

@@ -29,8 +29,8 @@ included with this module.
 Compatibility
 -------------
 
-``pdoc`` has been tested on Python 2.6, 2.7 and 3.3. It seems to work on
-all three.
+``pdoc`` has been tested on Python 2.7, 3.3, 3.4 and 3.5. It seems to work on
+all five.
 
 Contributing
 ------------

pdoc/__init__.py

@@ -191,7 +191,8 @@ def __init__(self):
 from mako.lookup import TemplateLookup
 from mako.exceptions import TopLevelLookupException
 
-__version__ = '0.3.1'
+from ._version import version as __version__
+
 """
 The current version of pdoc. This value is read from `setup.py`.
 """
@@ -571,7 +572,7 @@ def __init__(self, module, docfilter=None, allsubmodules=False):
             # modules and module level variables.
             if inspect.isfunction(obj) or inspect.isbuiltin(obj):
                 self.doc[name] = Function(name, self, obj)
-            elif inspect.ismethod(obj):
+            elif inspect.ismethod(obj) or inspect.ismethoddescriptor(obj):
                 self.doc[name] = Function(name, self, obj)
             elif inspect.isclass(obj):
                 self.doc[name] = Class(name, self, obj)
@@ -915,6 +916,9 @@ def __init__(self, name, module, class_obj):
             if inspect.ismethod(obj):
                 self.doc[name] = Function(name, self.module, obj.__func__,
                                           cls=self, method=True)
+            elif inspect.ismethoddescriptor(obj):
+                self.doc[name] = Function(name, self.module, obj,
+                                          cls=self, method=False)
             elif inspect.isfunction(obj):
                 self.doc[name] = Function(name, self.module, obj,
                                           cls=self, method=False)
@@ -1103,7 +1107,37 @@ def fmt_param(el):
             s = getspec(self.func)
         except TypeError:
             # I guess this is for C builtin functions?
-            return ['...']
+            # try to get signature from 1st line in docstring
+            try:
+                docstring_line1 = self.docstring.splitlines()[0]
+                # if 1st line does not end with '*', keep
+                # appending lines till we find one that does.
+                nline = 0
+                if not docstring_line1.endswith('*'):
+                    endswithstar = False; nline = 1
+                    while not endswithstar:
+                        next_line = self.docstring.splitlines()[nline]
+                        if not next_line.startswith(' '):
+                            docstring_line1 += ' '
+                        docstring_line1 += next_line
+                        endswithstar = next_line.endswith('*')
+                        nline += 1
+            except IndexError:
+                docstring_line1 = None
+            sig = ['...']
+            if docstring_line1 is not None:
+                try:
+                    func_name = docstring_line1.split('(')[0].split('`')[1]
+                    if func_name == self.name:
+                        sig =\
+                        [docstring_line1.partition('(')[-1].rpartition(')')[0]]
+                    # remove 1st line (or lines) from docstring
+                    # (the ones that contain the function signature)
+                    self.docstring =\
+                    ''.join(self.docstring.splitlines(True)[nline+1:])
+                except:
+                    pass
+            return sig
 
         params = []
         for i, param in enumerate(s.args):

scripts/pdoc → pdoc/__main__.py

@@ -26,6 +26,7 @@
     xrange = range
 
 version_suffix = '%d.%d' % (sys.version_info[0], sys.version_info[1])
+
 default_http_dir = path.join(tempfile.gettempdir(), 'pdoc-%s' % version_suffix)
 
 parser = argparse.ArgumentParser(
@@ -384,7 +385,7 @@ def process_html_out(impath):
         print(out)
 
 
-if __name__ == '__main__':
+def main():
     if args.version:
         print(pdoc.__version__)
         sys.exit(0)
@@ -499,3 +500,6 @@ def docfilter(o):
         quit_if_exists(module)
         html_out(module)
         sys.exit(0)
+
+if __name__=="__main__":
+    main_()

setup.py

@@ -1,28 +1,29 @@
+from sys import version_info as v
+if any([v < (2, 7), (3,) < v < (3, 3)]):
+    raise Exception("Unsupported Python version %d.%d. Requires Python >= 2.7 "
+                    "or >= 3.3." % v[:2])
+from setuptools import setup, find_packages
 import codecs
-from distutils.core import setup
-import os.path as path
-
-install_requires = ['mako', 'markdown < 2.5']
-try:  # Is this really the right way? Couldn't find anything better...
-    import argparse
-except ImportError:
-    install_requires.append('argparse')
+from os import path
 
 cwd = path.dirname(__file__)
-longdesc = codecs.open(path.join(cwd, 'longdesc.rst'), 'r', 'utf-8').read()
-version = '0.0.0'
-with codecs.open(path.join(cwd, 'pdoc', '__init__.py'), 'r', 'utf-8') as f:
-    for line in f:
-        if line.startswith('__version__'):
-            exec(line.strip())
-            version = __version__
-            break
+with codecs.open(path.join(cwd, 'longdesc.rst'), 'r', 'utf-8') as f:
+    longdesc = f.read()
 
 setup(
     name='pdoc',
     author='Andrew Gallant',
     author_email='[email protected]',
-    version=version,
+    use_scm_version={
+        'version_scheme': 'guess-next-dev',
+        'local_scheme': 'dirty-tag',
+        'write_to': 'pdoc/_version.py'
+    },
+
+    setup_requires=[
+        'setuptools>=18.0',
+        'setuptools-scm>1.5.4'
+    ],
     license='UNLICENSE',
     description='A simple program and library to auto generate API '
                 'documentation for Python modules.',
@@ -42,15 +43,22 @@
         'Programming Language :: Python :: 3',
     ],
     platforms='ANY',
-    packages=['pdoc'],
+    packages=find_packages(),
     package_data={'pdoc': ['templates/*']},
     data_files=[('share/pdoc', ['README.md', 'longdesc.rst',
                                 'UNLICENSE', 'INSTALL', 'CHANGELOG']),
                 ('share/doc/pdoc', ['doc/pdoc/index.html']),
                ],
-    scripts=['scripts/pdoc'],
     provides=['pdoc'],
-    requires=['argparse', 'mako', 'markdown'],
-    install_requires=install_requires,
-    extras_require={'syntax_highlighting': ['pygments']},
+    install_requires=[
+        'mako', 'markdown'
+    ],    
+    extras_require={
+        'syntax_highlighting': ['pygments']
+    },
+    entry_points={
+        'console_scripts': [
+            'pdoc = pdoc.__main__:main',
+        ],
+    },    
 )