Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

A simple program and library to auto generate API documentation for Python modules.

Project description

pdocs - Documentation Powered by Your Python Code.


PyPI version Build Status codecov Join the chat at https://gitter.im/pdocs/community License Downloads


Read Latest Documentation - Browse GitHub Code Repository


pdocs is a library and a command line program to discover the public interface of a Python module or package. The pdocs script can be used to generate Markdown or HTML of a module's public interface, or it can be used to run an HTTP server that serves generated HTML for installed modules.

pdocs is an MIT Licensed fork of pdoc with the goal of staying true to the original vision layed out by the projects creator.

NOTE: For most projects, the best way to use pdocs is using portray.

asciicast

Features

  • Support for documenting data representation by traversing the abstract syntax to find docstrings for module, class and instance variables.
  • For cases where docstrings aren't appropriate (like a namedtuple), the special variable __pdocs__ can be used in your module to document any identifier in your public interface.
  • Usage is simple. Just write your documentation as Markdown. There are no added special syntax rules.
  • pdocs respects your __all__ variable when present.
  • pdocs will automatically link identifiers in your docstrings to its corresponding documentation.
  • When pdocs is run as an HTTP server, external linking is supported between packages.
  • The pdocs HTTP server will cache generated documentation and automatically regenerate it if the source code has been updated.
  • When available, source code for modules, functions and classes can be viewed in the HTML documentation.
  • Inheritance is used when possible to infer docstrings for class members.

The above features are explained in more detail in pdocs's documentation.

pdocs is compatible with Python 3.6 and newer.

Quick Start

The following guides should get you up using pdocs in no time:

  1. Installation - TL;DR: Run pip3 install pdocs within your projects virtual environment.
  2. Command Line Usage - TL;DR: Run pdocs server YOUR_MODULES to test and pdocs as_html YOUR_MODULES to generate HTML.
  3. API Usage - TL;DR: Everything available via the CLI is also easily available programmatically from within Python.

Why Create pdocs?

I created pdocs to help power portray while staying true to the original vision of pdoc and maintain MIT license compatibility. In the end I created it to help power better documentation websites for Python projects.

I hope you too find pdocs useful!

~Timothy Crosley

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pdocs, version 1.0.1
Filename, size File type Python version Upload date Hashes
Filename, size pdocs-1.0.1-py3-none-any.whl (32.8 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size pdocs-1.0.1.tar.gz (29.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page