mitmproxy / pdoc

API Documentation for Python Projects

mitmproxy

mitmproxy is an interactive, SSL/TLS-capable intercepting proxy with a console interface for HTTP/1, HTTP/2, and WebSockets.

mitmdump is the command-line version of mitmproxy. Think tcpdump for HTTP.

mitmweb is a web-based interface for mitmproxy.

Installation

The installation instructions are here. If you want to install from source, see CONTRIBUTING.md.

Documentation & Help

General information, tutorials, and precompiled binaries can be found on the mitmproxy website.

The documentation for mitmproxy is available on our website:

If you have questions on how to use mitmproxy, please use GitHub Discussions!

Contributing

As an open source project, mitmproxy welcomes contributions of all forms.

pdoc's Issues

KeyError: "__slots__"

This is more likely to be package-specific but I'm not sure if this has to do with the target package or an internal bug in pdoc.

I've successfully run pdoc on several instances for various packages and individual modules. However, when trying to run it against the impacket package (http://corelabs.coresecurity.com/index.php?module=Wiki&action=view&type=tool&name=Impacket) it will run into an error in a subdirectory. The stacktrace eventually leads to "KeyError: 'slots'".

How to generate all doc for the package test?

test
init.py
test1.py
test2.py

I want to generate the python doc for the package test but the following command not work, anything wrong?
pdoc --html --html-dir /tmp/test/ --all-submodules --overwrite /test/

How to run from the Python IDLE?

The package docs says pdoc is mostly a commandline tool and those were the only examples given. However, it was briefly mentioned that one could use pdoc.Module class or pdoc.html function but without much detail. I tried it and I got an error that pdoc was giving an unexpected argument to the markdown module, possibly due to changes in a newer version of Markdown?

Am I doing it wrong, is there a standard way of using pdoc from Python? There are many cases and for many users that running pdoc from within Python would be preferred.

>>> import pdoc
>>> pdoc.html("pyagg")

Traceback (most recent call last):
  File "<pyshell#13>", line 1, in <module>
    pdoc.html("pyagg")
  File "C:\Python27\lib\site-packages\pdoc\__init__.py", line 270, in html
    link_prefix=link_prefix, source=source)
  File "C:\Python27\lib\site-packages\pdoc\__init__.py", line 675, in html
    **kwargs)
  File "C:\Python27\lib\site-packages\mako\template.py", line 443, in render
    return runtime._render(self, self.callable_, args, data)
  File "C:\Python27\lib\site-packages\mako\runtime.py", line 803, in _render
    **_kwargs_for_callable(callable_, data))
  File "C:\Python27\lib\site-packages\mako\runtime.py", line 835, in _render_context
    _exec_template(inherit, lclcontext, args=args, kwargs=kwargs)
  File "C:\Python27\lib\site-packages\mako\runtime.py", line 860, in _exec_template
    callable_(context, *args, **kwargs)
  File "_html_mako", line 237, in render_body
  File "_html_mako", line 37, in show_module
  File "_html_mako", line 479, in render_show_module
  File "_html_mako", line 110, in mark
  File "C:\Python27\lib\site-packages\markdown\__init__.py", line 493, in markdown
  File "C:\Python27\lib\site-packages\markdown\__init__.py", line 159, in __init__
  File "C:\Python27\lib\site-packages\markdown\__init__.py", line 185, in registerExtensions
    ext_args = ext_name[pos+1:-1]
  File "C:\Python27\lib\site-packages\markdown\__init__.py", line 291, in build_extension
    root = self.parser.parseDocument(self.lines).getroot()
TypeError: makeExtension() got an unexpected keyword argument 'linenums'

Restrict class interface?

Hi,

Subclassing bloated classes (like cmd.Cmd) will result in pdoc showing all methods from the inheritance tree, which is a lot.

Is there some kind of __all__ at the class level to restrict these? The Cmd class for example has lots of internal methods that do not begin with underscores, and I would like to omit those from the documentation.

Any ideas how to go about this?

pdoc doesn't find methods of cython extension types

Ran into this when trying to use pdoc to generate html docs from docstrings in my project (netcdf4-python). If you have a Cython extension type, for example

cdef class Shrubbery:
   """A class of Shrubbery"""
   cdef int width, height
   def __init__(self, w, h):
        self.width = w
        self.height = h
   def describe(self):
        """descibe the shubbery"""
        print "This shrubbery is", self.width, \
            "by", self.height, "cubits."

pdoc will generate the documentation for the class, and it's instance variables, but not it's methods. Is this a known issue? If so, are there workarounds?

Doctests are interpreted by the HTML template

When producing the output in HTML mode, doctests are simply interpreted as if they were part of markdown syntax and are replaced by (three) blockquotes.

For instance if you have the following code in a test.py file:

def f():
    '''
    >>> f()
    2
    '''
    return 2

Launching pdoc on that file with pdoc --html test.py will produce a HTML file where the docstring is replaced by the following code:

<blockquote>
<blockquote>
<blockquote>
<p>f()
2</p>
</blockquote>
</blockquote>
</blockquote>

Therefore the >>> are removed and the line return is ignored which makes the doctests hardly readable.

Instance variable docstrings are lost if the variable is redefined

It appears that when an instance variable is redefined below its original definition (which includes the docstring), then the docstring gets lost.

For example:

class Test:
    def __init__(self, name=None):
        self.name = 'Mike'
        '''Name of person'''
        self.age = 30
        '''Age of person'''
        self.gender = None
        '''Gender of person'''

produces:

while this:

class Test:
    def __init__(self, name=None):
        self.name = 'Mike'
        '''Name of person'''
        self.age = 30
        '''Age of person'''
        self.gender = None
        '''Gender of person'''

        self.name = name
        self.gender = 'Male'

produces:

Shouldn't the docstring be locked down once it's found (unless another attached docstring is found)?

code samples inline

It seems that writing example code only works at the top level.

For example, #!python gets parsed correctly as part of a module's comments, but is not if it is part of the docstring of a function or class.

Import Error if module is not defined in this environment

test.py:

import fooooooo

Traceback (most recent call last):
File "C:\Python27\Scripts\pdoc", line 454, in
module = imp.load_source('pdoc_file_module', fp, f)
File "User\work\test.py", line 17, in
import bdf
ImportError: No module named fooooooo

My project works in an environment who constructs python module dynamically. I can't use pdoc in this environment. How can I ignore this module and continue generate docs?

Thx for the help.

submodule not showing

I have a directory structure

folder_a
-- folder_b/
---- file_a.py
---- file_b.py

The page for folder_b shows only file_a as a sub module. Any ideas why this may be the case? Everything imports correctly, as I checked in a terminal.

Idea: special handling for Exception subclasses

It would be nice if pdoc outputted "exception MyCustomException" instead of "class MyCustomException".

UML Diagrams

Do you have any plans to integrate UML diagram generation. I find it really useful to view the entire class hierarchy visually.

Dynamically add/remove packages from HTTP server

It would be nice if it were possible to start the HTTP server, and then when someone creates a new package to somehow "add it" to the HTTP server that's running.

For example, if I have this set up for my org, it'll be run as root. I'm not sure how I'd add a package once the server is running, aside from restarting the server once I've installed the package

Way to hide Python prompt in examples

It would be nice to be able to click something to hide the Python prompts in examples, like you can in the Numpy docs

AttributeError: 'FullArgSpec' object has no attribute 'keywords'

I just installed version 0.1.5 and ran:

mkdir apidocs ; cd apidocs ; pdoc --html ../doorstop --overwrite

I get the following trackback (but index.html was generated):

Traceback (most recent call last):
  File "/Users/Browning/Drive/Programs/Libraries/Doorstop/bin/pdoc", line 487, in <module>
    html_out(module)
  File "/Users/Browning/Drive/Programs/Libraries/Doorstop/bin/pdoc", line 336, in html_out
    html_out(submodule)
  File "/Users/Browning/Drive/Programs/Libraries/Doorstop/bin/pdoc", line 336, in html_out
    html_out(submodule)
  File "/Users/Browning/Drive/Programs/Libraries/Doorstop/bin/pdoc", line 336, in html_out
    html_out(submodule)
  File "/Users/Browning/Drive/Programs/Libraries/Doorstop/bin/pdoc", line 334, in html_out
    raise e
  File "/Users/Browning/Drive/Programs/Libraries/Doorstop/bin/pdoc", line 327, in html_out
    source=not args.html_no_source)
  File "/Users/Browning/Drive/Programs/Libraries/Doorstop/lib/python3.3/site-packages/pdoc.py", line 652, in html
    **kwargs)
  File "/Users/Browning/Drive/Programs/Libraries/Doorstop/lib/python3.3/site-packages/mako/template.py", line 443, in render
    return runtime._render(self, self.callable_, args, data)
  File "/Users/Browning/Drive/Programs/Libraries/Doorstop/lib/python3.3/site-packages/mako/runtime.py", line 807, in _render
    **_kwargs_for_callable(callable_, data))
  File "/Users/Browning/Drive/Programs/Libraries/Doorstop/lib/python3.3/site-packages/mako/runtime.py", line 839, in _render_context
    _exec_template(inherit, lclcontext, args=args, kwargs=kwargs)
  File "/Users/Browning/Drive/Programs/Libraries/Doorstop/lib/python3.3/site-packages/mako/runtime.py", line 865, in _exec_template
    callable_(context, *args, **kwargs)
  File "_html_mako", line 262, in render_body
  File "_html_mako", line 32, in show_module
  File "_html_mako", line 637, in render_show_module
  File "_html_mako", line 406, in show_func
  File "/Users/Browning/Drive/Programs/Libraries/Doorstop/lib/python3.3/site-packages/pdoc.py", line 1056, in spec
    return ', '.join(self.params())
  File "/Users/Browning/Drive/Programs/Libraries/Doorstop/lib/python3.3/site-packages/pdoc.py", line 1088, in params
    keywords = getattr(s, 'varkw', s.keywords)
AttributeError: 'FullArgSpec' object has no attribute 'keywords'

Force pdoc to generate documentation for __get__?

Attached is a simple example where pdoc doesn't generate documentation for the __get__ method of a class. My guess is this method is considered not public, which seems reasonable.
Is there a way to force pdoc to process it still?

class Base(object):
    def __init__(self):
        """Constructor."""
        self.x = 1

    def __get__(self, instance, owner):
        "Set method."
        return self.x

And the output:

leo@lily:~/$ pdoc test.py
Module test
-----------

Classes
-------
Base 
    Ancestors (in MRO)
    ------------------
    test.Base
    __builtin__.object

    Instance variables
    ------------------
    x

    Methods
    -------
    __init__(self)
        Constructor.

Generating documentation for my code only

I just started using pdoc today after struggling to find a usable automatic documentation tool. So far, so good. My only problem is this: I use wxpython extensively and when pdoc generates documentation from my package, it also includes documentation for code that is part of wx, not part of my code (eg, if my class derives from wx.Window, the documentation includes ALL the methods from wx.Window, not just mine). How can I avoid this?

Why does the list of ancestors include the class itself?

See for example http://pdoc.burntsushi.net/pdoc#pdoc.Function
The list of ancestors include Function (so Function is an ancestor of itself?)

Link to class not created without the --external-links option

I'm generating documentation for my data_utils package. Under data_utils.gridded.grid I have a class defined:

class Grid:
    """
    ...
    """
    def __init__(...)

But when I generate documentation with this command:

pdoc data_utils --overwrite --html --html-dir docs/api

Any references in modules' docstrings (ex. data_utils.gridded.plotting) to data_utils.gridded.grid.Grid do not become links. However, when I include the --external-links arg:

pdoc data_utils --overwrite --external-links --html --html-dir docs/api

data_utils.gridded.grid.Grid does become a link. So why is this considered "external"?

Parsing Epytext

Sorry the ignorance. Is there a way of 'forcing' pdoc to parse docstrings in Epytext format as the example below:

def load_config(filename, option):
    """
    Loads and tests input parameters.

    @param filename: input filename
    @param option: option name
    @return: returns a valid config value
    """

Thanks

Documentation in the presence of an `__init__.py` with imports

Please, how exactly is supposed to be documented, a package with an __init__.py containing imports? Is pdoc supposed to document the imported items in-place? It seems to not do it, and just listing sub-modules, and I wonder if it's the expected behaviour or not.

Changes to the HTML theme?

Finally a documentation tool that takes markdown! I was actually just creating a very similar package, but mine was a lot messier and less complete. I hope news of this package keeps spreading, it would be a great revelation to the many Python programmers (esp beginners) who want to spend less time documenting their work and do it in a more intuitive language. Sphinx really can be a pain, and I still have not gotten it to work for me (too much configuration).

I really loved the sleek look of the pdoc theme. However, there were just some minor issues that I think would make it even better. It might be a lot to ask, but if there is easy access and control over the output html tags, and if you agree with my suggestions, this should really just be about changing some of the HTML tags, and adding some new ones.

• When browsing the pdoc pages of my own multilevel package, I noticed that there was no link to help me get "up" on level, or even back to the top/main package page. This way it made me feel like I was stuck on one page at a time, as there was no easy way for me to quickly go back and regain an overview of the package structure or of how far I had progressed into it, short of using the browsers back-button. The "Index" header at the top of the sidepanel could be a link for going back to the top, and a browsing tree showing the relative location within the package might also be useful.
• If there is a module-level docstring with some intro/overview text, add a link to that module docstring in the sidebar index list, as well as sublinks reflecting any markdown headings within that module docstring, This would allow package authors to give their users a gentler intro to each module with more context, philosophy, and usage examples, before jumping into the details. It would also be more conducive to a proper full-length front-page, with links to sections on installations, philosophy, basic usage examples, etc.
• Make the sidebar follow the screen (instead of scrolling along with the content), making it is easier to quickly jump between sections without having to always scroll up to the top first, and thus giving the users a better understanding and overview.
• Of a somewhat personal preference, I would have liked to see the color of the sidebar a bit darker like the gray used on the Py3 site to give it more depth and better differentiate it from the main content. Same goes for the main text headers of the variables, functions, classes, and methods, which could have a darker tint to their gray background, to make them pop out more from the screen.
• On a related note, what are the possibilites for color and other theme styling for the user? Is there any available customization built into pdoc, such as colors, sidepane layout, or turning off the source code buttons, or would we have to go in and change pdoc itself? If there was at least some theme styling, that would give pdoc roughly the same flexible feature-set as Sphinx and still be much easier to use.

Let me know what you think is possible, or point me in the direction of where to start if was to make a pull request. And again, great work!

Relative import syntax not fully recognised

(sorry, error)

pdoc fails to run if any module uses zipimporter

This is what I get trying to run pdoc –http on Mac OS X Lion:

Traceback (most recent call last):
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/SocketServer.py", line 284, in _handle_request_noblock
    self.process_request(request, client_address)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/SocketServer.py", line 310, in process_request
    self.finish_request(request, client_address)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/SocketServer.py", line 323, in finish_request
    self.RequestHandlerClass(request, client_address, self)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/SocketServer.py", line 639, in __init__
    self.handle()
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/BaseHTTPServer.py", line 337, in handle
    self.handle_one_request()
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/BaseHTTPServer.py", line 325, in handle_one_request
    method()
  File "/usr/local/bin/pdoc", line 100, in do_GET
    modules.append((name, quick_desc(imp, name, ispkg)))
  File "/usr/local/bin/pdoc", line 253, in quick_desc
    fp = path.join(imp.path, name, '__init__.py')
AttributeError: 'zipimport.zipimporter' object has no attribute 'path'

This is caused by quick_desc assuming the importer has a path attribute. The zipimporter doesn't. The function should be rewritten to use get_source() (see importlib.abc.InspectLoader). As a temporary workaround, I changed the quick_desc function to start like this:

def quick_desc(imp, name, ispkg):
    if not hasattr(imp, "path"):
        return ''

That won't get a description for zipped modules, but at least they don't halt the program altogether.

Windows Powershell

Installed using pip to a Windows 8.1 Powershell environment.

Was unable to run the pdoc script as a shebang script. (Powershell requires a filename extension to make the script executable.)

Workaround was to run directly from the python interpreter.

pdoc --html -o foo.html <module>

Hi,

Can you add -o foo.html for --html option? Just for storing the html file in the foo.html file instead of <module>.m.html in . directory.

Thanks in advance,

Can I only document the module itself?

I am very happy to find pdoc! I looked at other choices and they were heavy and poorly documented. So excellent to find something that works right away and is easy to manipulate.

That said, I have spent a few hours with the code but haven't quite figured out how to restrict the scope of documentation to just the contents of the module. I want to be able to only document:

• module scope variables
• module scope functions
• classes in a module
• methods in a class in a module
• instance variables in a class in a module

A standard use case for this that I imagine isn't just mine is for unit tests. Including in the documentation all the methods inherited from UnitTest does not add useful information.

I think this applies generally for any situation where you want the documentation to only focus on the module source, rather than being comprehensive about all the context of that module. In my case, I am documenting an intentionally minimal library and a very strong design goal is keeping every aspect of it as brief and simple as possible.

I will happily provide a pull request if necessary to implement this.

Thanks!

Mongoengine compatibility

I'm trying to run pdoc on a program, and for the most part, it works well, except on one module that has mongoengine.Document subclasses.

mongoengine.Document has a class method "objects" so that if you have a class Foo(mongoengine.Document), then Foo.objects is a special "query set" object which can return all objects, or a filtered subset of them (based on subsequent chained methods).

Unfortunately, this doesn't seem to play nice with pdoc, which uses inspect.getmembers() to inspect the class. A simple example:

from mongoengine import Document
class Foo(Document):
    pass
import inspect
inspect.getmembers(Foo)

Result: this raises mongoengine.connection.ConnectionError: "You have not defined a default connection". Running pdoc on this causes the same exception, but with a deeper stack trace.

The pdoc documentation says "If the name is defined in a different module, it is not public", and since the class method "Document.objects" is defined in the mongoengine module, I would expect it not to be part of the "public interface", and thus not be documented by pdoc. But perhaps I'm misunderstanding.

At least, I'd like to be able to declare a custom blacklist so that it can know to avoid calling getattr(cls, 'objects') on any Document subclasses.

Search Bar

It would be good to have a search bar for fuzzy searching. Maybe you can draw inspiration from Sublime Text's implementation.

Mathjax and equations

Would it be possible to add in a dependency to Mathjax.js so that we can render equations as well?

Hello there and can I please have closure comments represented or am I doing something wrong?

Mr. Sushi himself asked that I explain here the problem that I am having: http://stackoverflow.com/questions/1125970/python-documentation-generator/18258983?noredirect=1#comment46361911_18258983.

Here's the requested example:

def Example( ):
'''
Some comments.
'''

def deco(funct):

    def wrapper(*args, **kargs):

        ##############################
        # start a closure

        def exampleclosure():
            '''
            Some comments about the closure.
            '''

            return "Example() was run."

        # end a closure
        ##############################

        print funct()
        print  exampleclosure()

    return wrapper  

return deco

@example()
def dummy():
return "Ran dummy."

dummy()

So yes, I do a lot of decorators. And here's the pdoc output:

nummatenv)mike@Presario:~/retailbacktest/code$ pdoc example.py
Ran dummy.
Example() was run.

Module example

Functions

Example()
Some comments.

dummy(_args, *_kargs)
(nummatenv)mike@Presario:~/retailbacktest/code$

So of course I was hoping to see some output that contains "Some comments about the closure." But there is none. (Markdown accentuates "Module example" and "Functions" due to the lines of dashes that are in the pdoc output, but you must be familiar with that.)

Thanks much for all of the good work,
-Mike

Support keywords (like returns, example,etc)

Like sphinx, can you provide keywords like returns or example to document such things?

Thanks a lot,

Methods are reported as Static Methods with Python 3

Hello,

First of all thanks a lot for pdoc which is a wonderful tool and a pleasure to work with.

I noticed that if I generate documentation with Python 3, simple methods are reported as static methods. I tried to play a bit with the source code to fix it but it didn't seem trivial (forcing method=True when creating Function objects).

It may be that the semantics of inspect.ismethod and inspect.isfunction have changed between Python 2 and Python 3 and method in types are not reported as methods anymore because they haven't been bound yet.

Is this a known issue?

I'll try to dig more into the code when I have some free time.

Pdoc seems to not follow `__wrapped__`

Pdoc seems to not follow the __wrapped__ attribute, to keep track of functions wrapped by a decorator. All decorated functions (which is all functions for me personally), are documented with something like def fun(*args, **kargs).

Function annotations seems to be ignored too, both with decorated and non-decorated functions.

By the way, thanks for the idea of using Markdown ;-) .

HTTP Server and UTF-8 on Windows 8.1

On Windows 8.1 within a Powershell environment, using the command:

pdoc --http

and then seeking to load a page in the browser raised an exception (see below).

The fix was to edit line 264 from "utf-8" to "ISO-8859-1".

Exception report begins:

Exception happened during processing of request from ('127.0.0.1', 9378) Traceback (most recent call last): File "c:\Python27\Lib\SocketServer.py", line 295, in _handle_request_noblock self.process_request(request, client_address) File "c:\Python27\Lib\SocketServer.py", line 321, in process_request self.finish_request(request, client_address) File "c:\Python27\Lib\SocketServer.py", line 334, in finish_request self.RequestHandlerClass(request, client_address, self) File "c:\Python27\Lib\SocketServer.py", line 651, in __init__ self.handle() File "c:\Python27\Lib\BaseHTTPServer.py", line 340, in handle self.handle_one_request() File "c:\Python27\Lib\BaseHTTPServer.py", line 328, in handle_one_request method() File ".\env\Scripts\pdoc", line 100, in do_GET modules.append((name, quick_desc(imp, name, ispkg))) File ".\env\Scripts\pdoc", line 264, in quick_desc for i, line in enumerate(f): File "C:\Users\xxx\Projects\marrs\env\lib\codecs.py", line 681, in next return self.reader.next() File "C:\Users\xxx\Projects\marrs\env\lib\codecs.py", line 612, in next line = self.readline() File "C:\Users\xxx\Projects\marrs\env\lib\codecs.py", line 527, in readline data = self.read(readsize, firstline=True) File "C:\Users\xxx\Projects\marrs\env\lib\codecs.py", line 474, in read newchars, decodedbytes = self.decode(data, self.errors) UnicodeDecodeError: 'utf8' codec can't decode byte 0xf6 in position 0: invalid start byte

select modules to include in index

The default html server index, in Python module list, includes all available Python modules. Is there a way to restrict which modules show up here?

error: can't copy 'doc/pdoc/index.html': doesn't exist or not a regular file

That's what I get if I try to run "python setup.py install" with the latest code in the repository. Perhaps it's an uncommitted file in your build?

Source Code for decorated functions not correct

When getting source code for functions that have been decorated, either the source code of the decorator is returned (which is not ideal) or, if using the decorator module, the empty list is returned.

I've fixed this and sent a pull request.

Public/private view

I patched my local installation so that is provides either a public view or a private view of a module.

The rational is that it's useful to see the documentation of a module's private items to review/work-with/understand it.

I'm using a query string for this: ?private=false or ?private=true. I would like to know if it seems OK to use a query string or if the option should appears in the base URL.

I will wait for the review of the already pending pull-requests before I add this patch to my fork and do a pull-request from it.

Also just wanted to say I like pdoc, it really helps me, although I had to fix it in multiple ways (my issue is that I don't really know if my fixes are required to me only or if they are of interest to some others too).

Template files are searched for in the wrong location

I'm trying to use pdoc on a installed-two-weeks-ago Debian Jessie machine, but I get this message:

$ pdoc --html some-module
Traceback (most recent call last):
  File "/usr/local/bin/pdoc", line 487, in <module>
    html_out(module)
  File "/usr/local/bin/pdoc", line 334, in html_out
    raise e
IOError: [Errno 2] No template at any of: /usr/share/pdoc/templates/html.mako, /usr/local/lib/python2.7/dist-packages/templates/html.mako

I installed python (2.7.6) and pip via apt-get:

sudo apt-get install python
sudo apt-get install python-pip

I installed pdoc via pip:

sudo pip install pdoc

I can see that the html.mako template file exists in the /usr/local/share/pdoc tree, but pdoc seems to look for it in /usr/share/pdoc. After a quick glance at the pdoc code, it seems to get the prefix from the sys.prefix attribute, which seems to have the value /usr on my computer. Apparently pip used another prefix when it installed the files.

I don't think I have set up things in a weird way, but please tell me if you want me to try something. I would be happy to help debugging this, but I don't know where to start.

--template-dir does not work

That's because template_path list is processed on pdoc module import which happen before options processing.

Default keyword arguments not HTML-escaped

Simple example:

def a(b=object()):
  pass

Because the repr for this object is of the form "<object object at 0x7fa508b860a0>", and because pdoc doesn't escape the opening or closing tags, the output looks like this:

def a(b=)

As far as I can tell, it also breaks some of the HTML - items underneath this entry become nested under the definition of the offending function. If you generate the HTML for this code, the bug should be apparent (I reproduced this in Chromium):

def a(b=object()):
  pass
def b(c=object()):
  pass
def c(d=object()):
  pass
def d(e=object()):
  pass
def e(f=object()):
  pass

document linking scheme; spawn more tickets

Hi,
I am having trouble getting pdoc to create links to modules from within sub-modules of a package.

Example:

1. File foo/init.py:

"""
Package foo:

  * The `bar` module (no link)
  * The `.bar` module (no link)
  * The `foo.bar` module (link -> ok)
"""

__all__ = ["bar", "baz"]

1. File foo/bar.py:

"""
Module bar:

  * The `baz` module (no link)
  * The `.baz` module (no link)
  * The `foo.baz` module (link when shown on foo package page -> ok; No link when shown on foo.bar module page -> issue #1)
  * The `foo` package (no link -> issue #2)
  * The `..foo` package (no link)
"""

class Bar(object):
    pass

1. File foo/baz.py:

"""
Module baz
"""

class Baz(object):
    pass

The pdoc documentation states that links need to be start with the package. In doing so, the link to 'foo.baz' in sub-module 'bar' is generated as a link in the version of sub-module 'bar' that is shown on the 'foo' page. However, on the 'foo.bar' page, the link to 'foo.baz' is formatted with monospace font, but is not generated as a link (marked as issue #1 in the code above).

Second, the link to the package 'foo' in sub-module 'foo.bar' is not generated as a link either (marked as issue #2 in the code above).

I have added some more variations, just to try them out.

Is there a documentation about the link generation by pdoc, and more generally, about which flavor of markdown it supports?

Regards,
Andy

decorated functions

Is there an easy way to allow pdoc to access the doc of decorated functions?

For example, how can I make pdoc document:

@memoize
def func(a, b, c):
"""
Doc string
"""
return a, b, c

Customizing pdoc's html output

Is it possible to customize the html output, add my own css, etc.?

Reason for no module internal link?

I would like to know about the reason for not having module internal links in the generated documentation. My guess is that is may not always be easy, when as an example, a documentation string refers to a function parameter which is of the same name as an item defined in the module (PyLint warns about it, by the way).

Is this guess indeed the reason or is there another reason?

I “patched” my html.mako to display internal links, and am asking this question to know if it's relevant to propose this patch here.

I'm also actually to display references to function parameters in function documentation strings, with a specific class (I mean, HTML class), if feasible (under investigation).

--all-submodules flag still respects __all__

Running pdoc with the --all-submodules flag doesn't seem to have any effect on the generated documentation.

Example: running pdoc --html mymodule.py --all-submodules against the following code

class MyPublicClass(object):
    """docstring for MyPublicClass"""
    def __init__(self, arg):
        self.arg = arg


class PrivateClass(object):
    """docstring for PrivateClass"""
    def __init__(self, arg):
        self.arg = arg


__all__ = ['MyPublicClass']

results in only MyPublicClass being included in the docs.

Pdoc commandline script name conflict

When using pdoc for the first time I encountered an error with the commandline script that got placed into Python27/Scripts. First off, the file did not have the .py extension, so I had to add it. Secondly, when the commandline script tried importing pdoc from site-packages it just ended up importing itself (because the commandline script had the same name as the site-packages pdoc), resulting in a nameerror when trying to run the import_module() function. Changing the name of the commandline script fixed this error.

I am surprised noone else have gotten this error? Should be a quick fix anyway. I am on Windows 8, 32 bit Py27.

Python 2.6 compatibility (markdown dependency issue)

Hi. It is not a pdoc issue per say, but it might be useful to update the documentation.

You're keeping pdoc compatible with Python 2.6 (which is a good thing for the unlucky people still stuck with it). But the Python markdown package dropped Python 2.6 support in its 2.5 release.

Therefore currently a fresh install of pdoc from PyPi does not work. This is easily worked around by downgrading markdown to version 2.4.1, but the cause of the problem may be difficult to figure out.

The exception raised by markdown is caught and re-raised in html_out() in the pdoc script, so we lose the original backtrace from markdown, so users may have some difficulty seeing that the compatibility issue is with markdown. See this sample backtrace:

Traceback (most recent call last):
  File "/home/ubuntu/py-virtualenv/test-pdoc/bin/pdoc", line 491, in <module>
    html_out(module)
  File "/home/ubuntu/py-virtualenv/test-pdoc/bin/pdoc", line 338, in html_out
    raise e
ImportError: No module named importlib

Or, if installing the backported importlib for 2.6 from PyPi, this other error thrown by markdown:

Traceback (most recent call last):
  File "/home/ubuntu/py-virtualenv/test-pdoc/bin/pdoc", line 491, in <module>
    html_out(module)
  File "/home/ubuntu/py-virtualenv/test-pdoc/bin/pdoc", line 338, in html_out
    raise e
AttributeError: 'module' object has no attribute 'captureWarnings'

find a better way to get module descriptions

As pointed out in #7, importlib.abc.InspectLoader should be used to load the source code to get a module description from a module loader. But this appears to only be available in Python 3, so its implementation should fail gracefully in Python 2. (i.e., Return an empty string.)