{"id":16508816,"url":"https://github.com/goerz/better-apidoc","last_synced_at":"2025-03-16T18:32:32.525Z","repository":{"id":51808227,"uuid":"84279129","full_name":"goerz/better-apidoc","owner":"goerz","description":"A version of sphinx-apidoc with support for templating","archived":false,"fork":false,"pushed_at":"2021-05-10T20:27:52.000Z","size":51,"stargazers_count":32,"open_issues_count":4,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-27T12:20:48.465Z","etag":null,"topics":["apidoc","documentation-generator","python","sphinx","sphinx-doc"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goerz.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-08T04:40:47.000Z","updated_at":"2024-01-08T10:33:01.000Z","dependencies_parsed_at":"2022-09-12T12:10:33.917Z","dependency_job_id":null,"html_url":"https://github.com/goerz/better-apidoc","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goerz%2Fbetter-apidoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goerz%2Fbetter-apidoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goerz%2Fbetter-apidoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goerz%2Fbetter-apidoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goerz","download_url":"https://codeload.github.com/goerz/better-apidoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243826780,"owners_count":20354220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apidoc","documentation-generator","python","sphinx","sphinx-doc"],"created_at":"2024-10-11T15:47:54.688Z","updated_at":"2025-03-16T18:32:28.854Z","avatar_url":"https://github.com/goerz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# better-apidoc #\n\n[![PyPI version](https://badge.fury.io/py/better-apidoc.svg)](https://badge.fury.io/py/better-apidoc)\n\nA version of [sphinx-apidoc][] with support for templating\n\nAuthor: Michael Goerz \u003c\u003cgoerz@stanford.edu\u003e\u003e\n\nWebsite: [Github][]\n\n[Github]: https://github.com/goerz/better-apidoc#better-apidoc\n[sphinx-apidoc]: http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html\n\n\n## Installation ##\n\n    pip install better-apidoc\n\nThis will install `better-apidoc` in the current environment's `bin` folder.\n\n[virtualenv]: http://docs.python-guide.org/en/latest/dev/virtualenvs/\n[pipsi]: https://github.com/mitsuhiko/pipsi#pipsi\n[conda env]: http://conda.pydata.org/docs/using/envs.html\n\n## Templating ##\n\nThe `better-apidoc` script is a patched version of Sphinx' [apidoc.py]. After a lengthy gestation period, it is on track to be merged back into [apidoc.py]: https://github.com/sphinx-doc/sphinx/pull/6768\n\n**Note:** Due to changes in Sphinx 1.8, `better-apdic` in its current form can no longer run as a script from the command line, and must be run from inside `conf.py`, see \"Usage\" below.\n\nFundamentally, `better-apidoc` adds the `-t/--templates` option to the script.  If this option is not given, it is identical to `sphinx-apidoc`. With the option, [Jinja]-based templates are used for the generated ReST files. The template directory given via `-t` must contain the template files `module.rst` and `package.rst`.\n\n\nThe following variables are available in the templates:\n\n* *name*: the name of the module/package\n* *fullname*: the name of the module/package, including package path\n  (dot-separated)\n* *members*: list of names of all the members defined directly in the\n  module/package\n* *functions*: list all the functions in *members*\n* *classes*: list of all the classes in *members*\n* *exceptions*: list of all the exceptions in *members*\n* *data*: list of all the data items in *members*\n* *subpackages*: For packages, list of subpackage names. Empty list for modules\n* *submodules*: For packages, list of submodule names. Empty list of modules\n\nFurthermore, the function `get_members` is made available to the template:\n\n    def get_members(\n            typ=None, include_imported=False, out_format='names',\n            in_list=None, includeprivate=opts.includeprivate, known_refs=None):\n        \"\"\"Return a list of members of the current module\n\n        Args:\n            typ (None or str): One of None, 'function', 'class', 'exception',\n                'data'. If not None, only members of the corresponding type\n                 will be returned\n            include_imported (bool): If True, include members that are imported\n                from other modules. If False, only return members that are\n                defined directly in the module.\n            out_format (str): One of 'names', 'fullnames', 'refs', and 'table'\n            in_list (None or str): If not None, name of a module\n                attribute (e.g. '__all__'). Only members whose names appears in\n                the list will be returned.\n            includeprivate (bool): If True, include members whose names starts\n                with an underscore\n            know_refs (None or dict or str): If not None, a mapping of names to\n                rull rst-formatted references. If given as a str, the mapping\n                will be taken from the module attribute of the given name. This\n                is used only in conjunction with ``out_format=refs``, to\n                override automatically detected reference location, or to\n                provide references for object that cannot be located\n                automatically (data objects).\n\n        Returns:\n            list: List of strings, depending on `out_format`.\n\n            If 'names' (default), return a list of the simple names of all\n            members.\n\n            If 'fullnames', return a list of the fully qualified names\n            of the members.\n\n            If 'refs', return a list of rst-formatted links.\n\n            If 'table', return a list of lines for a rst table similar to that\n            generated by the autosummary plugin (left column is linked member\n            names, right column is first sentence of the docstring)\n\n\n        Note:\n            For data members, it is not always possible to determine whther\n            they are imported or defined locally. In this case, `in_list` and\n            `known_refs` may be used to achieve the desired result.\n\n            If using ``in_list='__all__'`` for a package you may also have to\n            use ``include_imported=True`` to get the full list (as packages\n            typically export members imported from their sub-modules)\n        \"\"\"\n\nYou can use this in a template as e.g.\n\n    {% set all_refs = get_members(in_list='__all__', include_imported=True, out_format='refs') %}\n    {% if all_refs %}\n        ``__all__``: {{ all_refs|join(\", \") }}\n    {%- endif %}\n\nto get a linked list of members in the `__all__` list of a module. Note that the\ntemplate variables *members*, *functions*, *classes*, *exceptions*, and *data*\nall could be obtained by using `get_members` as well; they are provided as\nvariables for convenience only.\n\nThe `package.rst` template will be used when rendering any package. The\n`module.rst` template will be used when rendering modules if the\n`-s/--separate` option is given, or if the `\u003cmodule_path\u003e` only contains\nmodules. Note that if `\u003cmodule_path\u003e` contains a package and the `-s/--separate`\nis not given, the `module.rst` template will not be used.\n\nThe addition of templates to `apidoc` addresses [Sphinx issue #3545]. That is, it\nis now possible to have a list of members with short summaries at the top of the\nAPI documentation that links to the more detailed information below.\nIt is also directly addresses the demand for this feature expressed on\n[Stackoverflow].\n\nSee\n[package.rst](https://github.com/mabuchilab/QNET/blob/develop/docs/_templates/package.rst)\nand\n[module.rst](https://github.com/mabuchilab/QNET/blob/develop/docs/_templates/module.rst)\nfor an example template. These render to e.g.\n\u003chttps://qnet.readthedocs.io/en/latest/API/qnet.algebra.core.operator_algebra.html\u003e\n\n\n[apidoc.py]: https://github.com/sphinx-doc/sphinx/blob/master/sphinx/apidoc.py\n[Jinja]: http://jinja.pocoo.org\n[`__imported_data__`]: https://github.com/mabuchilab/QNET/blob/4e637b18c53cbee598ed58c3b7f7820dd54216db/qnet/algebra/__init__.py#L56\n[Sphinx issue #3545]: https://github.com/sphinx-doc/sphinx/issues/3545\n[Stackoverflow]: http://stackoverflow.com/questions/29385564/customize-templates-for-sphinx-apidoc\n\n\n## Usage ##\n\nDue to [changes in Sphinx 1.8][issue14], `better_apidoc` can no longer be run as an independent script. Instead, it must be set up in Sphinx's `conf.py`. In `conf.py`, define a function like this:\n\n    def run_apidoc(app):\n        \"\"\"Generage API documentation\"\"\"\n        import better_apidoc\n        better_apidoc.APP = app\n        better_apidoc.main([\n            'better-apidoc',\n            '-t',\n            os.path.join('.', '_templates'),\n            '--force',\n            '--no-toc',\n            '--separate',\n            '-o',\n            os.path.join('.', 'API'),\n            os.path.join('..', 'src', 'krotov'),\n        ])\n\nYou will have to adjust the last two lines: `os.path.join('.', 'API')` is the location relative to `conf.py` where the API rst files should be generated. In the last line, `os.path.join('..', 'src', 'krotov')` is the location of the package code (I strongly advocate the [use of a `src` directory][srcdir]).\n\nThen, at the end of `conf.py`, add the following code:\n\n    def setup(app):\n        app.connect('builder-inited', run_apidoc)\n\n\n\n\nFor an full example, see the [`conf.py` file of the krotov project][krotovconf]\n\n[krotovconf]: https://github.com/qucontrol/krotov/blob/master/docs/conf.py\n[srcdir]: https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure\n\n## History ##\n\nv0.1.0 (2017-03-08): first public release\n\nv0.1.1 (2017-03-12): handle custom autodocumenters\n\nv0.1.2 (2017-03-12): support for (non-standard) `__local_data__` and `__imported_data__` class attributes to properly identify data members\n\nv0.1.3 (2018-03-14): support Sphinx 1.7\n\nv0.1.4 (2018-03-24): support both Sphinx 1.6 and 1.7\n\nv0.2.0 (2018-07-01):\n\n* make function `get_members` available to templates\n* remove template variables *member_imports*, *members_imports_refs*, *all_refs*: their functionality is now achieved with `get_members`\n* remove use of non-standard `__local_data__` and `__imported_data__` module attributes. These can still be used via the `in_list` argument of `get_members`.\n* add capability to generate autosummary-like tables, via ``out_format='table'`` in `get_members` (but solving autosummary's problem of not generating links for imported members)\n* **This release breaks templates written for v0.1.x**\n\nv0.3.0 (2019-04-02): Adapt to changes in Sphinx 1.8 ([#14][issue14]). As a result, `sphinx-apidoc` can no longer run as a standalone script, but must be called from inside `conf.py`.\n\nv0.3.1 (2019-04-04): Fix calls to Sphinx's `get_documenter` function to work for any version of version of Sphinx (tested on 1.6-2.0)\n\nv0.3.2 (2021-05-10): Compatibility update for Sphinx 4.0 ([#17][issue17])\n\n\n[issue14]: https://github.com/goerz/better-apidoc/issues/14\n[issue17]: https://github.com/goerz/better-apidoc/issues/17\n\n## License ##\n\nThis software is available under the terms of the BSD license. See [LICENSE]\nfor details.\n\n[LICENSE]: LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoerz%2Fbetter-apidoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoerz%2Fbetter-apidoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoerz%2Fbetter-apidoc/lists"}