| Name | autoclasstoc JSON |
| Version |
1.7.0
JSON |
| download |
| home_page | None |
| Summary | Add a succinct TOC to auto-documented classes. |
| upload_time | 2024-10-15 18:01:50 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.6 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
************
autoclasstoc
************
.. image:: https://img.shields.io/pypi/v/autoclasstoc.svg
:target: https://pypi.python.org/pypi/autoclasstoc
.. image:: https://img.shields.io/pypi/pyversions/autoclasstoc.svg
:target: https://pypi.python.org/pypi/autoclasstoc
.. image:: https://img.shields.io/readthedocs/autoclasstoc.svg
:target: https://autoclasstoc.readthedocs.io/en/latest/?badge=latest
.. image:: https://img.shields.io/github/actions/workflow/status/kalekundert/autoclasstoc/test.yml?branch=master
:target: https://github.com/kalekundert/autoclasstoc/actions
.. image:: https://img.shields.io/codecov/c/gh/kalekundert/autoclasstoc
:target: https://app.codecov.io/gh/kalekundert/autoclasstoc
It's surprisingly difficult to document large Python classes in a way that's
easy for users to navigate. Most projects use the ``autodoc`` Sphinx plugin,
which simply puts the complete documentation for each class member one after
another. While this does fully document the class, it doesn't give the user a
quick way to see everything the class can do. This makes classes of even
moderate complexity difficult to navigate. It also encourages projects to be
stingy about which class members to include in the documentation (e.g.
excluding special methods, inherited methods, private methods, and/or
undocumented methods), to the further detriment of the user.
What's needed is for each class to have a succinct table of contents (TOC)
that:
- Is organized into sections that will be meaningful to the user. Different
projects and classes may call for different sections, e.g. public/private
methods, methods that share a decorator, methods with a common prefix, etc.
- Includes every method of the class (so that the documentation is complete),
while still making it easy for the user to get a sense for what the class
does and find what they're looking for.
- Collapses inherited methods. Complex classes in particular can inherit a lot
of methods from their parent classes, and while these methods should be
present in the TOC (since they're part of the class), collapsing them makes
it easier for the user to grok the functionality provided by the class
itself.
``autoclasstoc`` provides a new Restructured Text directive that is all of
these things. It also works well with ``autodoc`` and ``autogen``, and should
be easy to incorporate into any existing project.
See the `complete documentation`__ for more information (including examples).
__ https://autoclasstoc.readthedocs.io/en/latest
Raw data
{
"_id": null,
"home_page": null,
"name": "autoclasstoc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Kale Kundert <kale@thekunderts.net>",
"download_url": "https://files.pythonhosted.org/packages/87/9f/e3ef0f487fb0ced67f5f527cc0b528a8607f1d2eefb77ff4f06316178e87/autoclasstoc-1.7.0.tar.gz",
"platform": null,
"description": "************\nautoclasstoc\n************\n\n.. image:: https://img.shields.io/pypi/v/autoclasstoc.svg\n :target: https://pypi.python.org/pypi/autoclasstoc\n\n.. image:: https://img.shields.io/pypi/pyversions/autoclasstoc.svg\n :target: https://pypi.python.org/pypi/autoclasstoc\n\n.. image:: https://img.shields.io/readthedocs/autoclasstoc.svg\n :target: https://autoclasstoc.readthedocs.io/en/latest/?badge=latest\n\n.. image:: https://img.shields.io/github/actions/workflow/status/kalekundert/autoclasstoc/test.yml?branch=master\n :target: https://github.com/kalekundert/autoclasstoc/actions\n\n.. image:: https://img.shields.io/codecov/c/gh/kalekundert/autoclasstoc\n :target: https://app.codecov.io/gh/kalekundert/autoclasstoc\n\nIt's surprisingly difficult to document large Python classes in a way that's \neasy for users to navigate. Most projects use the ``autodoc`` Sphinx plugin, \nwhich simply puts the complete documentation for each class member one after \nanother. While this does fully document the class, it doesn't give the user a \nquick way to see everything the class can do. This makes classes of even \nmoderate complexity difficult to navigate. It also encourages projects to be \nstingy about which class members to include in the documentation (e.g. \nexcluding special methods, inherited methods, private methods, and/or \nundocumented methods), to the further detriment of the user.\n\nWhat's needed is for each class to have a succinct table of contents (TOC) \nthat:\n\n- Is organized into sections that will be meaningful to the user. Different \n projects and classes may call for different sections, e.g. public/private \n methods, methods that share a decorator, methods with a common prefix, etc. \n\n- Includes every method of the class (so that the documentation is complete), \n while still making it easy for the user to get a sense for what the class \n does and find what they're looking for.\n\n- Collapses inherited methods. Complex classes in particular can inherit a lot \n of methods from their parent classes, and while these methods should be \n present in the TOC (since they're part of the class), collapsing them makes \n it easier for the user to grok the functionality provided by the class \n itself.\n\n``autoclasstoc`` provides a new Restructured Text directive that is all of \nthese things. It also works well with ``autodoc`` and ``autogen``, and should \nbe easy to incorporate into any existing project. \n\nSee the `complete documentation`__ for more information (including examples).\n\n__ https://autoclasstoc.readthedocs.io/en/latest\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Add a succinct TOC to auto-documented classes.",
"version": "1.7.0",
"project_urls": {
"Bug Tracker": "https://github.com/kalekundert/autoclasstoc/issues",
"Continuous Integration": "https://github.com/kalekundert/autoclasstoc/actions",
"Documentation": "https://autoclasstoc.readthedocs.io/en/latest/",
"Test Coverage": "https://coveralls.io/github/kalekundert/autoclasstoc",
"Version Control": "https://github.com/kalekundert/autoclasstoc"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7346a8f6be3b9f410949be16ca33ca5ac533398de705327d156446d298631f64",
"md5": "4eb779df99438b28f263c731d6bd086c",
"sha256": "00d7f8450d9fb043a500a0ac5fe9cda3699d51d68211f183178734f14df526ec"
},
"downloads": -1,
"filename": "autoclasstoc-1.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4eb779df99438b28f263c731d6bd086c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 12247,
"upload_time": "2024-10-15T18:01:48",
"upload_time_iso_8601": "2024-10-15T18:01:48.810553Z",
"url": "https://files.pythonhosted.org/packages/73/46/a8f6be3b9f410949be16ca33ca5ac533398de705327d156446d298631f64/autoclasstoc-1.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "879fe3ef0f487fb0ced67f5f527cc0b528a8607f1d2eefb77ff4f06316178e87",
"md5": "7bab19e5b530b26309e1e8628daaecda",
"sha256": "93a604be070a1f0ab19b0a0dd9d03d3fb16377da8a7a49ed8919692ef882775a"
},
"downloads": -1,
"filename": "autoclasstoc-1.7.0.tar.gz",
"has_sig": false,
"md5_digest": "7bab19e5b530b26309e1e8628daaecda",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 11193,
"upload_time": "2024-10-15T18:01:50",
"upload_time_iso_8601": "2024-10-15T18:01:50.231017Z",
"url": "https://files.pythonhosted.org/packages/87/9f/e3ef0f487fb0ced67f5f527cc0b528a8607f1d2eefb77ff4f06316178e87/autoclasstoc-1.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-15 18:01:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kalekundert",
"github_project": "autoclasstoc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "autoclasstoc"
}
