{"id":21861614,"url":"https://github.com/elcorto/sphinx-autodoc","last_synced_at":"2025-04-14T19:36:16.946Z","repository":{"id":85816251,"uuid":"51010999","full_name":"elcorto/sphinx-autodoc","owner":"elcorto","description":"Almost, but not quite, entirely unlike sphinx-apidoc. ","archived":false,"fork":false,"pushed_at":"2023-10-31T16:47:09.000Z","size":45,"stargazers_count":2,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-28T08:01:43.014Z","etag":null,"topics":["sphinx","sphinx-apidoc","sphinx-documentation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elcorto.png","metadata":{"files":{"readme":"README.md","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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-02-03T15:58:53.000Z","updated_at":"2023-10-31T14:17:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"0bf92d15-574c-4926-b15a-b526853b6a98","html_url":"https://github.com/elcorto/sphinx-autodoc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elcorto%2Fsphinx-autodoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elcorto%2Fsphinx-autodoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elcorto%2Fsphinx-autodoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elcorto%2Fsphinx-autodoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elcorto","download_url":"https://codeload.github.com/elcorto/sphinx-autodoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248946835,"owners_count":21187583,"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":["sphinx","sphinx-apidoc","sphinx-documentation"],"created_at":"2024-11-28T03:12:11.279Z","updated_at":"2025-04-14T19:36:16.924Z","avatar_url":"https://github.com/elcorto.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# About\n\n`sphinx-autodoc` is almost, but not quite, entirely unlike `sphinx-apidoc`\nprovided with Sphinx. It is a tool to automatically create `rst` source files,\nfrom which Sphinx can create API documentation, which means you can build API\ndocs in a fully automatic way without having to write a single `rst` file by hand.\n\nThis tool was created when `sphinx-apidoc` wasn't really around yet and later\nwe never got it to work the way we wanted :) More on the differences between\nthe two tools below.\n\n# Features\n\n* Full API doc. Each module will be treated by the\n  [`sphinx.ext.autosummary`][autosummary] extension. Files are written to\n  `source/generated/api` by default. Module doc strings (if present) are also\n  included. Every module member (class, function) is documented on a separate\n  page.\n* Optionally (`-i/--write-index`) create an initial `index.rst`. Reference hand\n  written docs (by default in `source/written/`) in there.\n* Optionally (`--write-doc`), pull module doc strings into a separate dir\n  (`source/doc/`) and also reference them in `source/index.rst` (if\n  `--write-index`).\n* `class.rst` template file (details below). Has been tested on numpy-ish code\n  bases using the numpy docstring format. It works well in conjunction with the\n  defaults that we implement and the recommended settings in Sphinx' `conf.py`.\n\nAPI docs generated with `sphinx-autodoc` can be found [here][imagecluster],\n[here][pwtools] or [here][psweep].\n\n\n# Install\n\n```sh\n$ git clone ...\n$ cd sphinx-autodoc\n$ pip install [-e] .\n```\n\n# Usage tl;dr\n\n```sh\n# Install your package since we need to import it\n$ cd /path/to/myproject\n$ pip install -e .\n\n# Call sphinx-autodoc, \"myproject\" is the package *name*\n$ cd /path/to/myproject/doc\n$ sphinx-autodoc myproject\n\n# Build docs with Sphinx\n$ make html\n$ firefox build/html/index.html\n\n# Build docs with Jupyter Book\n##$ jb build source\n##$ firefox source/_build/html/index.html\n```\n\n# Options\n\n```\nusage: sphinx-autodoc [-h] [-s SOURCE] [-a APIPATH] [-d DOCPATH]\n                      [-w WRITTENPATH] [-i] [--write-doc] [--no-write-api]\n                      [-X EXCLUDE]\n                      package\n\npositional arguments:\n  package               The name of the package to walk (e.g. 'scipy')\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -s SOURCE, --source SOURCE\n                        sphinx source dir below which all rst files will be\n                        written [source]\n  -a APIPATH, --apipath APIPATH\n                        dir (relative to SOURCE) for generated API rst files,\n                        written by default, may be turned off by --no-write-\n                        api [generated/api]\n  -d DOCPATH, --docpath DOCPATH\n                        dir (relative to SOURCE) for extra generated rst files\n                        with module doc strings in addition to having them in\n                        the API docs, use with --write-doc, off by default\n                        [generated/doc]\n  -w WRITTENPATH, --writtenpath WRITTENPATH\n                        dir (relative to SOURCE) with hand written rst files,\n                        an index.rst file must exist there, this will be added\n                        to SOURCE/index.rst if found, only needed with\n                        --write-index [written]\n  -i, --write-index     (over)write SOURCE/index.rst (a backup is made), not\n                        written by default\n  --write-doc           (over)write SOURCE/DOCPATH\n  --no-write-api        don't (over)write SOURCE/APIPATH\n  -X EXCLUDE, --exclude EXCLUDE\n                        regex for excluding modules, applied to the full\n                        module name [None]\n```\n\n# Examples\n\nWe provide a minimal, self-contained Python package with a doc dir for\nexperimentation: `example_package/autodoctest`. In particular, check out\n`example_package/autodoctest/doc/generate-doc.sh`. This implements a common\nworkflow: clean up old builds, call `sphinx-autodoc`, `make html`. Use this to\npurge and re-build all your docs.\n\n```sh\n$ cd example_package/autodoctest/\n$ pip install -e .\n$ cd doc\n$ ./generate-doc.sh\n$ firefox build/html/index.html\n```\n\n# Usage\n\n## With [`Jupyter Book`][jupyterbook]\n\nWe recently started using Jupyter Book instead of Sphinx directly and also\nplayed with the new `:recursive:` option of `sphinx.ext.autosummary`. Still\nAPI docs for each member end up on a single page. There [are ways to get\naround this by fiddling with\ntemplates](https://jupyterbook.org/en/stable/advanced/developers.html) but we\nended up using `sphinx-autodoc` to generate API docs and pointed\nJupyter Book to the `generated/api/index.rst` file in `source/_toc.yml`.\n\nAlso we don't use `_templates/autosummary/class.rst` in this case. Things still\nrender fine, so this template may be obsolete.\n\nCheck [this](https://github.com/elcorto/psweep/tree/main/doc) for how we use\nit, with only minor modifications to `generate-doc.sh`.\n\n## With Sphinx\n\n### Set up a doc dir using `sphinx-quickstart`\n\nIf you haven't already, create a sphinx doc dir for your project (lets assume\n`myproject/doc` with the source dir `myproject/doc/source` and the main index\nfile `myproject/doc/source/index.rst`).\n\n```sh\n$ cd myproject/doc\n$ sphinx-quickstart\n```\n\nChoose a separate source and build dir (e.g. `doc/source` and\n`doc/build`). Accept most other defaults.\n\n\n### Configuration\n\nInspect `doc/source/conf.py` and make sure you have at least these\nextensions enabled.\n\n```py\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.autosummary',\n    'sphinx.ext.napoleon',\n    'sphinx.ext.viewcode',\n    ]\n```\n\nWe use the [napoleon] extension instead of [numpydoc]. See\n`example_package/autodoctest/doc/source/conf.py` for more extensions.\n\nNow modify `doc/source/conf.py` to include these configs.\n\n```py\nautosummary_generate = True\n\nautodoc_default_options = {\n    'members': True,\n    # The ones below should be optional but work nicely together with\n    # example_package/autodoctest/doc/source/_templates/autosummary/class.rst\n    # and other defaults in sphinx-autodoc.\n    'show-inheritance': True,\n    'inherited-members': True,\n    'no-special-members': True,\n}\n```\n\nSee also `example_package/autodoctest/doc/source/conf.py`.\n\n\n### Notes for numpydoc, class template\n\nWe used to use [numpydoc] and numpy's class template in the past. However, with\nrecent Sphinx versions, the [napoleon] extension does a great job. Use our own\nclass template if you like in conjunction with that: copy\n`example_package/autodoctest/doc/source/_templates/autosummary/class.rst` to\nyour `doc/source/_templates/autosummary/`.\n\n\n### Use sphinx-autodoc\n\ntl;dr: See `example_package/autodoctest/doc/generate-doc.sh`\n\n\nNow walk through the package and create `rst` files. We use `-i` to create an\ninitial `source/index.rst`.\n\n```sh\n$ sphinx-autodoc -i -s doc/source myproject\n```\n\nNote that this will overwrite an existing `index.rst` file (a backup is\nmade however).\n\nYou can run the script from anywhere, provided that `myproject` is a\nPython package since we need to import it to inspect all its subpackages\nand modules. The source path `-s` must point to the dir where you want\nall `rst` files to be generated, which will usually be `doc/source/`.\n\nNow modify `source/index.rst` to suit you needs and then run `make html`\nusing the Makefile generated by `sphinx-quickstart` earlier. Inspect the\nrendered docs.\n\n```sh\n$ firefox build/html/index.html\n```\n\n# Difference to `sphinx-apidoc`\n\nThe first difference is that `sphinx-apidoc` gets pointed to\na *source tree*.\n\n```sh\n$ cd myproject/doc\n$ sphinx-apidoc -o source/generated/api ../src/myproject/\n```\n\nYou may need to fuzz around with `sys.path` in `conf.py` such that Sphinx finds\nyour code since the `autodoc` extension needs to import each sub-package and\nmodule anyway.\n\nFor this reason, we require your project to be installed and importable (which\nis easy and safe with `pip install [--no-deps] -e .`). The argument to\n`sphinx-autodoc` is thus the package *name*.\n\n```sh\n$ cd myproject/doc\n$ sphinx-autodoc myproject\n```\n\nIn fact you can run it from anywhere, but inside `myproject/doc` all defaults\n(`-s source`, `-a generated/api`) work.\n\nThe second difference is what we put into generated module stub files. Examples\nof generated files using the `example_package/autodoctest` package are listed\nbelow.\n\n`sphinx-apidoc` generates a `automodule` directive only, which will make all\ndocs for the module end up on a single page. We automatically create\n`autosummary` directives and list all module members. This makes Sphinx create\none page per member. We have found no way to do the same with Sphinx' own\ntools. If there is, ping me or send a PR against this file.\n\n## `sphinx-apidoc`\n\n```rst\nmain module\n===========\n\n.. automodule:: main\n   :members:\n   :undoc-members:\n   :show-inheritance:\n```\n\n## `sphinx-autodoc`\n\n```rst\n.. rst file which lists all members of the current module. They will be\n.. handled by the Sphinx autosummary extension.\n\nmain\n====\n\n.. Documentation string which may be at the top of the module.\n.. automodule:: autodoctest.main\n   :no-members:\n   :no-inherited-members:\n\n.. currentmodule:: autodoctest.main\n\n.. Links to members.\n.. autosummary::\n   :toctree:\n\n   Bar\n   Baz\n   Foo\n   func\n```\n\n\n[numpydoc]: https://numpydoc.readthedocs.io\n[napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html\n[autosummary]: https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html\n[imagecluster]: https://elcorto.github.io/imagecluster/generated/api/\n[pwtools]: https://elcorto.github.io/pwtools/generated/api/\n[psweep]: https://github.com/elcorto/psweep\n[jupyterbook]: https://jupyterbook.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felcorto%2Fsphinx-autodoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felcorto%2Fsphinx-autodoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felcorto%2Fsphinx-autodoc/lists"}