API Documentation for Python Projects

Overview

pdoc

pdoc documentation CI Status Code Coverage PyPI Version Supported Python Versions

API Documentation for Python Projects.

Example

pdoc -o ./html pdoc generates this website: pdoc.dev/docs.

Installation

pip install pdoc

pdoc is compatible with Python 3.8 and newer.

Usage

pdoc your_python_module
# or
pdoc ./my_project.py

Run pdoc pdoc to see pdoc's own documentation, run pdoc --help to view the command line flags, or check our hosted copy of the documentation.

Features

pdoc's main feature is a focus on simplicity: pdoc aims to do one thing and do it well.

  • Documentation is plain Markdown. There are no added special syntax rules.
  • First-class support for type annotations and all other modern Python 3 features.
  • Builtin web server with live reloading.
  • Customizable HTML templates.
  • Understands numpydoc and Google-style docstrings.
  • Standalone JS-free HTML output without additional dependencies.

Under the hood...

  • pdoc will automatically link identifiers in your docstrings to their corresponding documentation.
  • pdoc respects your __all__ variable when present.
  • pdoc will traverse the abstract syntax tree to extract type annotations and docstrings from constructors as well.
  • pdoc will automatically try to resolve type annotation string literals as forward references.
  • pdoc will use inheritance to resolve type annotations and docstrings for class members.

If you have substantially more complex documentation needs, we recommend using Sphinx!

Contributing

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

Dev Guide

Also, please feel free to join our developer Slack!

Slack Developer Chat

pdoc vs. pdoc3

This project is not associated with "pdoc3", which often falsely assumes our name. Quoting @BurntSushi, the original author of pdoc:

I'm pretty disgusted that someone has taken a project I built, relicensed it, attempted to erase its entry on the Python Wiki, released it under effectively the same name and, worst of all, associated it with Nazi symbols.

Source: https://github.com/pdoc3/pdoc/issues/64

In contrast, the pdoc project strives to uphold a healthy community where everyone is treated with respect. Everyone is welcome to contribute as long as they adhere to basic civility. We expressly distance ourselves from the use of Nazi symbols and ideology.


The pdoc project was originally created by Andrew Gallant and is currently maintained by Maximilian Hils.

Issues
  • support for markdown output

    support for markdown output

    Goals: add markdown as output format because readthedocs has support only for rst and md formats right now.

    • add cli options: --markdown, --walk-path, --walk-path-followlinks
    • change cli option --html-dir to --output-dir
    • add md.mako template based on text.mako
    • you can now specify many modules per one executing
    • walk-path option allows recursively find all modules in path via init.py file, '.py' extension and even via 'python' word in the shebang
    opened by Friz-zy 30
  • Can I only document the module itself?

    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!

    opened by marksweiss 18
  • Unable to run pdoc from command line

    Unable to run pdoc from command line

    This question was closed in the past, but the solution didn't solve it for me. I'm running Windows 7 and python 2.7

    I'm installing pdoc globally using "pip install pdoc". It says that it pip installs correctly, puts a file called 'pdoc' (no extension) into my Python27/Scripts (which is on my PATH), however when I type "pdoc" in the command line I get the following... 'pdoc' is not recognized as an internal or external command, operable program or batch file'

    The previous closed issue was solved by running "pip install --system pdoc" but that was for Ubuntu and doesn't seem to be an option for Windows.

    opened by CadBrad 17
  • Inconsistent module names when specifying multiple paths

    Inconsistent module names when specifying multiple paths

    I have one related question about the html output after running the above script.

    # script full path: C:\Dropbox\python\create_pdoc.py
    import pdoc
    from pathlib import Path
    myscripts = ["./myscript.py", "./path2/myscript.py", "./myscript3.py"]
    pdoc.pdoc(*myscripts, output_directory=Path("./_mydocs"))
    
    

    I run this script calling C:\python38\python C:\Dropbox\python\create_pdoc.py The .py scripts to be documented are in the same C:\Dropbox\python\ folder (or children folders, like the script inside path2 subfolder). I don't think their content is relevant for this question (they just contain a sample function definition followed by a docstring comment: """ my comments """).

    As expected, the output (3 html documents + index.html + search.js) is created in C:\Dropbox\python\_mydocs And index.html left menu shows links to the other 3 html docs in same order as they are in myscripts list, like this:

    Available Modules

    • Dropbox.python.myscript
    • myscript
    • Dropbox.python.myscript3

    What I don't understand is the reason why the 2nd one (located inside path2) shows no path information, while the 1st and 3rd (located in the same folder as my create_pdoc.py script) show the full path below C: (i.e. Dropbox.python.)

    How can I control that? I would have expected one of these results instead:

    Available Modules

    • myscript
    • path2.myscript
    • myscript3

    Available Modules

    • Dropbox.python.myscript
    • Dropbox.python.path2.myscript
    • Dropbox.python.myscript3

    ... either all or none scripts preceded by Dropbox.python. path (although I would prefer not to show it)

    Originally posted by @abubelinha in https://github.com/mitmproxy/pdoc/issues/322#issuecomment-1003104131

    bug 
    opened by mhils 17
  • After installing pdoc with pip it not recognised as an executable on Windows

    After installing pdoc with pip it not recognised as an executable on Windows

    Tried navigating to \Scripts, same result.

    opened by epogrebnyak 16
  • Add support for Google Style

    Add support for Google Style

    Google docstrings are increasingly common. There are definitely other users who use Google-style strings as well.

    I've implemented some very basic parsing for Google-style docstrings in html-google.mako. Seems like a project like this could benefit from natively supporting a few common docstring styles, so I'd be willing to generalize this to numpy-style as well and add a flag --style=google perhaps.

    Looking forward to hearing your thoughts! cc @BurntSushi for discussion as to if we should merge, cc @igordertigor because I thought you might be interested in seeing this.

    Google Style

    """
    A short description of the function goes here.
    
    Arguments:
        argname (type): Description.
        secondarg (type : default): Description.
    
    Returns:
        boolean: True on success.
    """
    
    opened by j6k4m8 15
  • SystemError: Parent module '' not loaded, cannot perform relative import

    SystemError: Parent module '' not loaded, cannot perform relative import

    I am trying to create a html documentation for a module with the following command:

    pdoc --html --overwrite huffman.py 
    

    But I am receiving the following error:

    Traceback (most recent call last):
      File "/Library/Frameworks/Python.framework/Versions/3.5/bin/pdoc", line 458, in <module>
        module = imp.load_source('__pdoc_file_module__', fp, f)
      File "/Library/Frameworks/Python.framework/Versions/3.5/lib/python3.5/imp.py", line 172, in load_source
        module = _load(spec)
      File "<frozen importlib._bootstrap>", line 693, in _load
      File "<frozen importlib._bootstrap>", line 673, in _load_unlocked
      File "<frozen importlib._bootstrap_external>", line 662, in exec_module
      File "<frozen importlib._bootstrap>", line 222, in _call_with_frames_removed
      File "/Users/cell/Desktop/ands/algorithms/greedy/huffman.py", line 56, in <module>
        from ...ds.MinPriorityQueue import *
    SystemError: Parent module '' not loaded, cannot perform relative import    
    

    I know that the problem is related to the fact that I am doing a relative import, which doesn't work because huffman.py is not being imported as I programmed it to be imported. So, currently, I am using the following code:

    if __name__ == "__main__":
        from os import path, sys
        BASE_DIR = path.dirname(path.dirname(path.dirname(__file__)))  # ands
        sys.path.append(BASE_DIR)
        from ds.MinPriorityQueue import *
    else:
            from ...ds.MinPriorityQueue import *
    

    Which is already a mess, because I am trying to handle both when this huffman.py file (or module) is run as main or imported from outside ands, which is the parent of the parent of the package where huffman.py is situated. To solve the problem, I did the following:

    from os import path, sys
    BASE_DIR = path.dirname(path.dirname(path.dirname(__file__)))  # ands
    sys.path.append(BASE_DIR)
    
    if __name__ == "__main__":
        from ds.MinPriorityQueue import *
    else:
        try:
            from ...ds.MinPriorityQueue import *
        except SystemError:
            from ds.MinPriorityQueue import *
    

    Unfortunately this is far from being simple, considered that what I want to achieve should be very simple.

    Any suggestions to simplify my code?

    opened by nbro 14
  • Template files are searched for in the wrong location

    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.

    opened by raek 13
  • Docstring flavors

    Docstring flavors

    I'm opening this ticket to unify discussion of docstring flavors. We have a wide range of requests for these, including:

    • Google style [#101]
    • reStructuredText [#111]
    • Markdown variants [#64]
    • Handling of doctests [#63]
    • Epytext [#35]
    • UML diagrams [#22]
    • ASCII Doc [#108]
    • Pre-formatted docstrings [#114]
    • Formulas [#87]

    I'm going to close all these tickets so that we can explore which direction to take in one place. When I first took on pdoc, I thought we could get away with supporting one and only one format. Having read carefully through all of the related tickets, I've now softened that a bit, and I think that there's an argument for being pragmatic.

    My feeling is that we should clearly cater for doctests and pre-formatted docstrings, and choose a more flexible markdown renderer that includes Github-style tables and the like. Equally, I feel we should clearly not include support for reStructuredText, which is way too large and complicated. I'm undecided about things like Google style and EpyText, which are intermediate.

    It's possible that we could use a Github-style type marker for this:

    """raw
       
        This is a pre-formatted docstring.
                     Indentation will be preserved.
    """
    

    And:

    """google
    A Google-style docstring.
    
    Arguments:
         argname (type): Description.
         secondarg (type : default): Description.
    
    Returns:
        boolean: True on success.
    """
    

    The downside of this is that it introduces a weirdness to docstrings that make them less nice for both humans in code editors and other documentation tools. Another possibility (fronted in some PRs) is to control this unilaterally for an entire module with a command-line flag. This has the issue that the format is not specified in the code (where I feel it should be), and that many modules will be heterogenous and require support for multiple formats. Thoughts?

    opened by cortesi 13
  • Pipe operand for type unions causes type annotation errors

    Pipe operand for type unions causes type annotation errors

    Problem Description

    Natively since Python 3.9, but using from __future__ import annotations on some version prior you can use syntax like str | int instead of Union[str, int]. This is supported by type parsers and python alike, but pdoc seems to not like it that much. While the website builds to a certain point, it doesn't complete the full generation.

    Steps to reproduce the behavior:

    1. Parse code with type unions using the pipe operand
    2. ???
    3. Profit

    System Information

    pdoc: 8.1.0
    Python: 3.9.9
    Platform: macOS-12.0.1-arm64-arm-64bit
    
    bug 
    opened by bczsalba 13
  • Display line numbers when viewing source code

    Display line numbers when viewing source code

    Problem Description

    Two related enhancement proposals:

    1. Are there any chances to (optionally) display source code line numbers in html documentation?
    2. Are there any chances to link to specific source code line numbers in html documentation?

    Proposal

    1. When you click view-source at the right side of a function definition (or Class, or whatever), source code lines are shown. Is it possible that these lines come with the line number shown on the left side? (as an option, like many text editors offer)
    2. I noticed that each line of source code is rendered as a single <span class="sd">source code</span> If each span is preceded with a <a name="lnXXXX"> tag, then that line (number XXXX) would be linkable using module.html#lnXXXX

    Alternatives

    1. For showing line numbers:
    • Offer this as an option in pdoc.render.configure(show_line_numbers: bool)
    • Offer this as a clickable option in html output, next to view-source on the right side
    • Offer both options
    1. For introducing linking anchors:
    • Offer this as an option in pdoc.render.configure(create_line_anchors: bool) Probably this would imply that view-source should be active by default in rendered html output as well, not needing to click anywhere (otherwise, module.html#lnXXXX links to specific span tag anchors won't do anything if those span tags are not already visible when module.html is loaded).

    Additional context

    https://pdoc.dev/docs/pdoc/render.html#configure https://pdoc.dev/docs/pdoc/doc.html#Doc.source_lines Useful to complement use case described in #325 and specially in #327

    enhancement 
    opened by abubelinha 4
  • Configure module index

    Configure module index

    Problem Description

    Currently when generating via pdoc, the index.html creates a "module" index with no content, other then a search bar. When using the documentation, all pages also contain a relative link to this module index, making it inevitable to be seen by customers.

    Proposal

    I would like to be able to configure the logo, and default content. Ideally specify one module and render that modules description. Ofc this has the additional problem of duplicating documentation - so not sure how to approach this best.

    enhancement 
    opened by Fohlen 9
  • Markdown Export

    Markdown Export

    hey any chance we can create a ticket for the markdown output support? I saw there is one that was closed but the markdown branch is over a hundred commits behind and I would love to track it properly :)

    there's quite a bit wrong with simply renaming html files to md files right now. I am using mkdocs but, for example, the search feature of mkdocs will pick up on the html and show a lot of nonsense in the results because of it. I'm also struggling with links not working because of differences in how mkdocs treats files as directories in the URL but pdoc links to html files (that do not exist). I think proper markdown output support would make this challenge at least a tiny bit easier since the jinja templates should be simpler to modify to fit any weird mkdocs→pdoc linking issues.

    thanks for the work!

    Originally posted by @Zeelot in https://github.com/mitmproxy/pdoc/issues/203#issuecomment-949286955

    enhancement 
    opened by mhils 10
  • Support embedding local images (through reST directives)

    Support embedding local images (through reST directives)

    Problem Description

    First of all, it's great to see this package being developed again! I've only just begun converting my docstrings into external documentation and this looks like it will be a great fit for what I need!

    "A picture is worth a thousand words" and this is sometimes especially true for documentation! Well-written documentation should always be the standard of course, and I'm very glad this project makes it easier to read docs in a browser rather than having to always read the code docstrings themselves. Sometimes, though, being able to include an image for a difficult operation or concept would make a world of difference.

    For instance, my research focuses on a subfield of deep learning. Having a way to display small images/graphs of before and after a function is run on an array (or something similar) would go a long way into making certain difficult operations easier to conceptualize for myself and others.

    Proposal

    It would be great if this project added a way to include images into the output HTML files. One way to do this might be to use the reST directive .. image:: which could easily be added to the bottom of a docstring. That way, the docstring itself is minimally disrupted, but when viewing the generated external documentation, images could be easily seen.

    Additionally, an extra bonus would be if this supported the google doc style instead of only restructured text. I mention this because including markdown files mentions using the __docformat__ = "restructuredtext", and I assume if adding images were to be supported, it might be done in a similar way. Unfortunately our code follows the Google doc style and setting __docformat__ = "restructuredtext" messes up the rendering.

    Alternatives

    I've considered using small Markdown snippets like

    ![image](/path/to/image.png)
    

    and then including them in a docstring via

    .. include:: snippet.md
    

    However, this only displays the text content of the markdown file and not the included image.

    Additional context

    This is something that pdoc3 says they support through the reST .. image:: directive so hopefully it wouldn't be too much trouble to also integrate it here. I haven't tried using this feature from that package, but their documentation does say it is an option.

    This looks similar to #272, however, I'm only concerned with being able to include images in the static HTML files, not display any warnings or caution symbols. Additionally, I believe (or hope! 😁 ) that this is within the scope of the project as markdown does support image display, while it didn't have native admonition support.

    enhancement 
    opened by StellarStorm 2
  • Support documenting function parameters using `:param` or `@param` syntax

    Support documenting function parameters using `:param` or `@param` syntax

    Problem Description

    As noted in #143 , many Python projects use the format :param <param-name>: <description> or @param <param-name>: <description>, but this format for documenting function parameters is not recognized by pdoc.

    Proposal

    I would love to see pdoc add support for these formats for documenting function parameters. I work with several projects that use this format. Additionally, I feel like this format looks better in the code (particularly inside of IDE help texts).

    Alternatives

    Converting these docstrings to the google or numpydoc formats described in #153 is burdensome for larger projects that want to switch to using pdoc, especially since pdoc otherwise works so beautifully out of the box.

    Additional context

    n/a

    enhancement 
    opened by jhale1805 2
  • Pick up Type Annotations From .pyi Stub Files (PEP-561)

    Pick up Type Annotations From .pyi Stub Files (PEP-561)

    Problem Description

    I'm building a native code Python extension module in Rust with PyO3. It can attach docstrings and function signatures to the module items, but AFAIK currently there is no way to add Python type information to the extension modules.

    PEP-561 was created to help to solve this issue. It defines type information "stubs" (.pyi files), which only carry type hints and signatures, but not the implementation or docstrings.

    I've created a PEP-561 compliant stubs package foo-stubs for my extension module foo, which contains the module type hints in its only __init__.pyi source file. This scheme was needed because PEP-561 does not support distributing type information as a part of module-only distributions.

    I have also verified that both mypy and PyCharm are able to extract and use type information distributed in this manner.

    Proposal

    pdoc is currently able to extract inline type hints from conventional .py sources. It would be great if pdoc was also able to pull the type information from .pyi stubs that are distributed alongside with the Python package sources or as a separate "-stubs" package.

    Alternatives

    The native code extension modules may gain the ability to encode the required type information at some point in the future, making .pyi type stubs obsolete.

    Additional context

    PyCharm is able to combine the docstrings and function signatures extracted from the extension module via introspection with the type hints extracted from the separately distributed .pyi files.

    enhancement help wanted 
    opened by ravenexp 2
  • pdoc is back!

    pdoc is back!

    Hi folks,

    pdoc has picked up steam again and we've just shipped a new stable release. 🚀

    This release fixes many longstanding issues, but also removes a few beloved features, namely Markdown output and the __pdoc__ variable. We'll see how far this goes and if we need to add them back. I have also taken the liberty to clean up the issue tracker. If you have any feedback, please don't hesistate to open a new issue!

    opened by mhils 17
This is a repository for "100 days of code challenge" projects. You can reach all projects from beginner to professional which are written in Python.

100 Days of Code It's a challenge that aims to gain code practice and enhance programming knowledge. Day #1 Create a Band Name Generator It's actually

SelenNB 4 Dec 4, 2021
📖 Generate markdown API documentation from Google-style Python docstring. The lazy alternative to Sphinx.

lazydocs Generate markdown API documentation for Google-style Python docstring. Getting Started • Features • Documentation • Support • Contribution •

Machine Learning Tooling 60 Jan 12, 2022
Automated Integration Testing and Live Documentation for your API

Automated Integration Testing and Live Documentation for your API

ScanAPI 1.2k Jan 3, 2022
Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.

Introduction Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without

Swagger 21.4k Jan 15, 2022
A curated list of awesome tools for Sphinx Python Documentation Generator

Awesome Sphinx (Python Documentation Generator) A curated list of awesome extra libraries, software and resources for Sphinx (Python Documentation Gen

Hyunjun Kim 778 Jan 5, 2022
Run `black` on python code blocks in documentation files

blacken-docs Run black on python code blocks in documentation files. install pip install blacken-docs usage blacken-docs provides a single executable

Anthony Sottile 297 Jan 8, 2022
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 4.4k Jan 7, 2022
Literate-style documentation generator.

888888b. 888 Y88b 888 888 888 d88P 888 888 .d8888b .d8888b .d88b. 8888888P" 888 888 d88P" d88P" d88""88b 888 888 888

Pycco 764 Jan 11, 2022
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 4.4k Jan 7, 2022
Project documentation with Markdown.

MkDocs Project documentation with Markdown. View the MkDocs documentation. Project release notes. Visit the MkDocs wiki for community resources, inclu

MkDocs 13.5k Jan 14, 2022
Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server.

sphinx-autobuild Rebuild Sphinx documentation on changes, with live-reload in the browser. Installation sphinx-autobuild is available on PyPI. It can

Executable Books 371 Jan 9, 2022
Your Project with Great Documentation.

Read Latest Documentation - Browse GitHub Code Repository The only thing worse than documentation never written, is documentation written but never di

Timothy Edmund Crosley 772 Jan 14, 2022
:blue_book: Automatic documentation from sources, for MkDocs.

mkdocstrings Automatic documentation from sources, for MkDocs. Features Python handler features Requirements Installation Quick usage Features Languag

Timothée Mazzucotelli 581 Jan 14, 2022
:blue_book: Automatic documentation from sources, for MkDocs.

mkdocstrings Automatic documentation from sources, for MkDocs. Features - Python handler - Requirements - Installation - Quick usage Features Language

null 580 Jan 12, 2022
Seamlessly integrate pydantic models in your Sphinx documentation.

Seamlessly integrate pydantic models in your Sphinx documentation.

Franz Wöllert 40 Jan 6, 2022
Documentation generator for C++ based on Doxygen and mosra/m.css.

mosra/m.css is a Doxygen-based documentation generator that significantly improves on Doxygen's default output by controlling some of Doxygen's more unruly options, supplying it's own slick HTML+CSS generation and adding a fantastic live search feature.

Mark Gillard 55 Dec 28, 2021
NetBox plugin for BGP related objects documentation

Netbox BGP Plugin Netbox plugin for BGP related objects documentation. Compatibility This plugin in compatible with NetBox 2.10 and later. Installatio

Nikolay Yuzefovich 67 Jan 10, 2022
Documentation of the QR code found on new Austrian ID cards.

Austrian ID Card QR Code This document aims to be a complete documentation of the format used in the QR area on the back of new Austrian ID cards (Per

Gabriel Huber 7 Aug 27, 2021
Swagger Documentation Generator for Django REST Framework: deprecated

Django REST Swagger: deprecated (2019-06-04) This project is no longer being maintained. Please consider drf-yasg as an alternative/successor. I haven

Marc Gibbons 2.6k Dec 28, 2021