| Name | pdocs JSON |
| Version |
1.2.0
JSON |
| download |
| home_page | |
| Summary | A simple program and library to auto generate API documentation for Python modules. |
| upload_time | 2022-12-19 07:59:11 |
| maintainer | |
| docs_url | None |
| author | Timothy Crosley |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://timothycrosley.github.io/pdocs/)
_________________
[](http://badge.fury.io/py/pdocs)
[](https://travis-ci.org/timothycrosley/pdocs)
[](https://codecov.io/gh/timothycrosley/pdocs)
[](https://gitter.im/pdocs/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[](https://pypi.python.org/pypi/pdocs/)
[](https://pepy.tech/project/pdocs)
_________________
[Read Latest Documentation](https://timothycrosley.github.io/pdocs/) - [Browse GitHub Code Repository](https://github.com/timothycrosley/pdocs/)
_________________
`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](https://github.com/mitmproxy/pdoc)'s original implementation by Andrew Gallant (@BurntSushi).
with the goal of staying true to the original vision layed out by the project's creator.
NOTE: For most projects, the best way to use `pdocs` is using [portray](https://timothycrosley.github.io/portray/).
[](https://asciinema.org/a/265744)
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](http://docs.python.org/2.7/library/collections.html#namedtuple-factory-function-for-tuples-with-named-fields)),
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](https://timothycrosley.github.io/pdocs/docs/quick_start/1.-installation/) - TL;DR: Run `pip3 install pdocs` within your projects virtual environment.
2. [Command Line Usage](https://timothycrosley.github.io/pdocs/docs/quick_start/2.-cli/) - TL;DR: Run `pdocs server YOUR_MODULES` to test and `pdocs as_html YOUR_MODULES` to generate HTML.
3. [API Usage](https://timothycrosley.github.io/pdocs/docs/quick_start/3.-api/) - TL;DR: Everything available via the CLI is also easily available programmatically from within Python.
## Differences Between pdocs and pdoc
Below is a running list of intentional differences between [pdoc](https://github.com/mitmproxy/pdoc) and [pdocs](https://github.com/timothycrosley/pdocs):
- pdocs has built-in support for Markdown documentation generation (as needed by [portray](https://timothycrosley.github.io/portray/)).
- pdocs has built-in support for the inclusion of Type Annotation information in reference documentation.
- pdocs requires Python 3.6+; pdoc maintains Python2 compatibility as of the latest public release.
- pdocs uses the most recent development tools to ensure long-term maintainability (mypy, black, isort, flake8, bandit, ...)
- pdocs generates project documentation to a temporary folder when serving locally, instead of including a live server. An intentional trade-off between simplicity and performance.
- pdocs provides a simplified Python API in addition to CLI API.
- pdocs is actively maintained.
- pdocs uses [hug CLI and sub-commands](https://github.com/timothycrosley/pdocs/blob/master/pdocs/cli.py#L1), pdoc uses [argparse and a single command](https://github.com/mitmproxy/pdoc/blob/master/pdoc/cli.py#L1).
- pdoc provides textual documentation from the command-line, pdocs removed this feature for API simplicity.
## Notes on Licensing and Fork
The original pdoc followed the [Unlicense license](https://unlicense.org/), and as such so does the initial commit to this fork [here](https://github.com/timothycrosley/pdocs/commit/7cf925101e4ffc5690f2952ac9ad0b7b0410b4f8).
Unlicense is fully compatible with MIT, and the reason for the switch going forward is because MIT is a more standard and well-known license.
As seen by that commit, I chose to fork with fresh history, as the project is very old (2013) and I felt many of the commits that happened in the past might, instead of helping to debug issues, lead to red herrings due to the many changes that have happened
in the Python eco-system since that time. If you desire to see the complete history for any reason, it remains available on the original [pdoc repository](https://github.com/mitmproxy/pdoc).
## Why Create `pdocs`?
I created `pdocs` to help power [portray](https://timothycrosley.github.io/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
Raw data
{
"_id": null,
"home_page": "",
"name": "pdocs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Timothy Crosley",
"author_email": "timothy.crosley@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/80/55/2aca02c7015f52e30fb7ce920b967276c1a4198812db703e322a0ed43390/pdocs-1.2.0.tar.gz",
"platform": null,
"description": "[](https://timothycrosley.github.io/pdocs/)\n_________________\n\n[](http://badge.fury.io/py/pdocs)\n[](https://travis-ci.org/timothycrosley/pdocs)\n[](https://codecov.io/gh/timothycrosley/pdocs)\n[](https://gitter.im/pdocs/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)\n[](https://pypi.python.org/pypi/pdocs/)\n[](https://pepy.tech/project/pdocs)\n_________________\n\n[Read Latest Documentation](https://timothycrosley.github.io/pdocs/) - [Browse GitHub Code Repository](https://github.com/timothycrosley/pdocs/)\n_________________\n\n\n`pdocs` is a library and a command line program to discover the public\ninterface of a Python module or package. The `pdocs` script can be used to\ngenerate Markdown or HTML of a module's public interface, or it can be used\nto run an HTTP server that serves generated HTML for installed modules.\n\n`pdocs` is an MIT Licensed fork of [pdoc](https://github.com/mitmproxy/pdoc)'s original implementation by Andrew Gallant (@BurntSushi).\n with the goal of staying true to the original vision layed out by the project's creator.\n\nNOTE: For most projects, the best way to use `pdocs` is using [portray](https://timothycrosley.github.io/portray/).\n\n[](https://asciinema.org/a/265744)\n\nFeatures\n--------\n\n* Support for documenting data representation by traversing the abstract syntax\n to find docstrings for module, class and instance variables.\n* For cases where docstrings aren't appropriate (like a\n [namedtuple](http://docs.python.org/2.7/library/collections.html#namedtuple-factory-function-for-tuples-with-named-fields)),\n the special variable `__pdocs__` can be used in your module to\n document any identifier in your public interface.\n* Usage is simple. Just write your documentation as Markdown. There are no\n added special syntax rules.\n* `pdocs` respects your `__all__` variable when present.\n* `pdocs` will automatically link identifiers in your docstrings to its\n corresponding documentation.\n* When `pdocs` is run as an HTTP server, external linking is supported between\n packages.\n* The `pdocs` HTTP server will cache generated documentation and automatically\n regenerate it if the source code has been updated.\n* When available, source code for modules, functions and classes can be viewed\n in the HTML documentation.\n* Inheritance is used when possible to infer docstrings for class members.\n\nThe above features are explained in more detail in pdocs's documentation.\n\n`pdocs` is compatible with Python 3.6 and newer.\n\n## Quick Start\n\nThe following guides should get you up using pdocs in no time:\n\n1. [Installation](https://timothycrosley.github.io/pdocs/docs/quick_start/1.-installation/) - TL;DR: Run `pip3 install pdocs` within your projects virtual environment.\n2. [Command Line Usage](https://timothycrosley.github.io/pdocs/docs/quick_start/2.-cli/) - TL;DR: Run `pdocs server YOUR_MODULES` to test and `pdocs as_html YOUR_MODULES` to generate HTML.\n3. [API Usage](https://timothycrosley.github.io/pdocs/docs/quick_start/3.-api/) - TL;DR: Everything available via the CLI is also easily available programmatically from within Python.\n\n## Differences Between pdocs and pdoc\n\nBelow is a running list of intentional differences between [pdoc](https://github.com/mitmproxy/pdoc) and [pdocs](https://github.com/timothycrosley/pdocs):\n\n- pdocs has built-in support for Markdown documentation generation (as needed by [portray](https://timothycrosley.github.io/portray/)).\n- pdocs has built-in support for the inclusion of Type Annotation information in reference documentation.\n- pdocs requires Python 3.6+; pdoc maintains Python2 compatibility as of the latest public release.\n- pdocs uses the most recent development tools to ensure long-term maintainability (mypy, black, isort, flake8, bandit, ...)\n- pdocs generates project documentation to a temporary folder when serving locally, instead of including a live server. An intentional trade-off between simplicity and performance.\n- pdocs provides a simplified Python API in addition to CLI API.\n- pdocs is actively maintained.\n- pdocs uses [hug CLI and sub-commands](https://github.com/timothycrosley/pdocs/blob/master/pdocs/cli.py#L1), pdoc uses [argparse and a single command](https://github.com/mitmproxy/pdoc/blob/master/pdoc/cli.py#L1).\n- pdoc provides textual documentation from the command-line, pdocs removed this feature for API simplicity.\n\n## Notes on Licensing and Fork\n\nThe original pdoc followed the [Unlicense license](https://unlicense.org/), and as such so does the initial commit to this fork [here](https://github.com/timothycrosley/pdocs/commit/7cf925101e4ffc5690f2952ac9ad0b7b0410b4f8).\nUnlicense is fully compatible with MIT, and the reason for the switch going forward is because MIT is a more standard and well-known license.\n\nAs seen by that commit, I chose to fork with fresh history, as the project is very old (2013) and I felt many of the commits that happened in the past might, instead of helping to debug issues, lead to red herrings due to the many changes that have happened\nin the Python eco-system since that time. If you desire to see the complete history for any reason, it remains available on the original [pdoc repository](https://github.com/mitmproxy/pdoc).\n\n## Why Create `pdocs`?\n\nI created `pdocs` to help power [portray](https://timothycrosley.github.io/portray/) while staying true to the original vision of `pdoc` and maintain\nMIT license compatibility. In the end I created it to help power better documentation websites for Python projects.\n\nI hope you, too, find `pdocs` useful!\n\n~Timothy Crosley\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple program and library to auto generate API documentation for Python modules.",
"version": "1.2.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "9486f80d566b1213fbb33e14230dbe67",
"sha256": "caca2829415e62d31eaab46c53cd77a2a14f132c73e48e25187331c3a9fc2459"
},
"downloads": -1,
"filename": "pdocs-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9486f80d566b1213fbb33e14230dbe67",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 35529,
"upload_time": "2022-12-19T07:59:09",
"upload_time_iso_8601": "2022-12-19T07:59:09.232986Z",
"url": "https://files.pythonhosted.org/packages/c8/9f/06545fcae3e8b4819101894c4d22a7765e88a94f724d5ac2af0c6a976eb4/pdocs-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "4269c9eba0481f737131f546817abf1e",
"sha256": "996ad4d5039b59a9a112d29abfb3995ec4ed8d8415ddce6947c3a5248adb428b"
},
"downloads": -1,
"filename": "pdocs-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "4269c9eba0481f737131f546817abf1e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 33378,
"upload_time": "2022-12-19T07:59:11",
"upload_time_iso_8601": "2022-12-19T07:59:11.114355Z",
"url": "https://files.pythonhosted.org/packages/80/55/2aca02c7015f52e30fb7ce920b967276c1a4198812db703e322a0ed43390/pdocs-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-19 07:59:11",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "pdocs"
}
