{"id":17477971,"url":"https://github.com/arunanshub/sphinx-nested-apidoc","last_synced_at":"2025-04-22T11:24:50.249Z","repository":{"id":44468759,"uuid":"331999624","full_name":"arunanshub/sphinx-nested-apidoc","owner":"arunanshub","description":"sphinx-nested-apidoc: When flattened is not enough.","archived":false,"fork":false,"pushed_at":"2025-04-17T22:34:25.000Z","size":860,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-18T12:23:26.026Z","etag":null,"topics":["documentation-generator","python","python3","sphinx","sphinx-documentation"],"latest_commit_sha":null,"homepage":"https://sphinx-nested-apidoc.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arunanshub.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","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,"zenodo":null}},"created_at":"2021-01-22T16:21:22.000Z","updated_at":"2025-04-17T22:34:28.000Z","dependencies_parsed_at":"2023-10-13T12:45:15.366Z","dependency_job_id":"b36c29c8-7aab-4284-b0e0-6c9c4ec141f5","html_url":"https://github.com/arunanshub/sphinx-nested-apidoc","commit_stats":{"total_commits":200,"total_committers":4,"mean_commits":50.0,"dds":"0.31999999999999995","last_synced_commit":"609770072269caddf1f0c5c282b8f37dbf275fc9"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arunanshub%2Fsphinx-nested-apidoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arunanshub%2Fsphinx-nested-apidoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arunanshub%2Fsphinx-nested-apidoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arunanshub%2Fsphinx-nested-apidoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arunanshub","download_url":"https://codeload.github.com/arunanshub/sphinx-nested-apidoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250229804,"owners_count":21396180,"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":["documentation-generator","python","python3","sphinx","sphinx-documentation"],"created_at":"2024-10-18T20:10:20.255Z","updated_at":"2025-04-22T11:24:50.222Z","avatar_url":"https://github.com/arunanshub.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"sphinx-nested-apidoc\n====================\n\nWhen flattened is not enough.\n\n.. image:: https://github.com/arunanshub/sphinx-nested-apidoc/actions/workflows/ci.yml/badge.svg\n   :alt: CI\n   :target: https://github.com/arunanshub/sphinx-nested-apidoc/actions/workflows/ci.yml\n\n.. image:: https://coveralls.io/repos/github/arunanshub/sphinx-nested-apidoc/badge.svg?branch=master\n   :target: https://coveralls.io/github/arunanshub/sphinx-nested-apidoc?branch=master\n   :alt: Coverage\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n   :alt: Black\n   :target: https://github.com/psf/black\n\n.. image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat\u0026labelColor=ef8336\n   :alt: isort\n   :target: https://pycqa.github.io/isort\n\n.. image:: https://img.shields.io/pypi/pyversions/sphinx-nested-apidoc\n   :target: https://pypi.org/project/sphinx-nested-apidoc\n   :alt: PyPI - Python Version\n\n.. image:: https://readthedocs.org/projects/sphinx-nested-apidoc/badge/?version=latest\n   :target: https://sphinx-nested-apidoc.readthedocs.io/en/latest/?badge=latest\n   :alt: Documentation Status\n\nInstallation\n++++++++++++\n\nUse ``pip`` or ``pip3`` to install ``sphinx-nested-apidoc``\n\n.. code-block:: bash\n\n   pip install sphinx-nested-apidoc\n\nor\n\n.. code-block:: bash\n\n   pip3 install sphinx-nested-apidoc\n\nIntroduction\n++++++++++++\n\n``sphinx-apidoc`` is a great tool for generating documentation, but it does not\nreplicate the directory structure of your package. ``sphinx-nested-apidoc``\naims to solve that problem.\n\nTutorial\n++++++++\n\nLet's say we have the following directory structure of our package:\n\n.. code-block:: text\n\n   mymodule/\n   ├── fruits/\n   │   ├── __init__.py\n   │   ├── mango.py\n   │   ├── pear.py\n   ├── animals/\n   │   ├── special/\n   │   │   ├── __init__.py\n   │   │   ├── doggo.py\n   │   │   └── catto.py\n   │   ├── __init__.py\n   │   ├── monke.py\n   │   └── chimp.py\n   ├── __init__.py\n   ├── base.py\n   └── exceptions.py\n\nAnd we want to generate documentation for this package in some directory ``docs/``.\n\nLet's see the difference.\n\nUsing ``sphinx-apidoc`` we get\n------------------------------\n\nWe use the following command:\n\n.. code-block:: bash\n\n   sphinx-apidoc -o docs/ mymodule/ -e\n\nIt generates:\n\n.. code-block:: text\n\n   docs/\n   ├── modules.rst\n   ├── mymodule.animals.chimp.rst\n   ├── mymodule.animals.monke.rst\n   ├── mymodule.animals.rst\n   ├── mymodule.animals.special.catto.rst\n   ├── mymodule.animals.special.doggo.rst\n   ├── mymodule.animals.special.rst\n   ├── mymodule.base.rst\n   ├── mymodule.exceptions.rst\n   ├── mymodule.fruits.mango.rst\n   ├── mymodule.fruits.pear.rst\n   ├── mymodule.fruits.rst\n   └── mymodule.rst\n\nThis is not very clean, obviously.\n\nUsing ``sphinx-nested-apidoc`` we get\n-------------------------------------\n\nWe use the following command:\n\n.. code-block:: bash\n\n   sphinx-nested-apidoc -o docs/ mymodule/\n\nIt generates:\n\n.. code-block:: text\n\n   docs/\n   ├── modules.rst\n   └── mymodule/\n       ├── animals/\n       │   ├── chimp.rst\n       │   ├── index.rst\n       │   ├── monke.rst\n       │   └── special/\n       │       ├── catto.rst\n       │       ├── doggo.rst\n       │       └── index.rst\n       ├── base.rst\n       ├── exceptions.rst\n       ├── fruits/\n       │   ├── mango.rst\n       │   ├── pear.rst\n       │   └── index.rst\n       └── index.rst\n\nLooks clean!\n\nWant to name the package something else?\n----------------------------------------\n\n.. code-block:: bash\n\n   sphinx-nested-apidoc --package-name src -o docs/ mymodule/\n\nIt generates:\n\n.. code-block:: text\n\n   docs/\n   ├── modules.rst\n   └── src/\n       ├── animals/\n       │   ├── chimp.rst\n       │   ├── index.rst\n       │   ├── monke.rst\n       │   └── special/\n       │       ├── catto.rst\n       │       ├── doggo.rst\n       │       └── index.rst\n       ├── base.rst\n       ├── exceptions.rst\n       ├── fruits/\n       │   ├── mango.rst\n       │   ├── pear.rst\n       │   └── index.rst\n       └── index.rst\n\nNote that ``mymodule`` has been renamed to ``src``.\n\nAs a Sphinx Extension\n---------------------\n\nYou can also use this as a sphinx extension.\n\nCreate a file called ``docs/conf.py`` and configure it like this:\n\n.. code-block:: python\n\n   # ...\n   extensions = [\n       \"sphinx_nested_apidoc\",\n       # ...other extensions\n   ]\n\n   # Name of the package directory.\n   sphinx_nested_apidoc_package_dir = \"packagename\"\n   # Name of the folder to put all the package documentation in. By default it is\n   # the name of the package itself.\n   sphinx_nested_apidoc_package_name = \"src\"\n   # ...\n\nAnd then run:\n\n.. code-block:: bash\n\n   sphinx-build docs docs/_build\n\nUsage Details\n+++++++++++++\n\n.. code-block:: text\n\n   usage: sphinx-nested-apidoc [-h] [-v | -q] [--version] [-f] [-n] -o DESTDIR\n                               [--package-name PACKAGE_NAME] [-s SUFFIX]\n                               [--implicit-namespaces]\n                               module_path ...\n\nGenerates nested directory from sphinx-apidoc's flattened files. It is simply a\nwrapper over sphinx-apidoc and you can pass additional arguments to it for\nextended configuration.\n\npositional arguments:\n   ``module_path``\n      Path to package to document.\n   ``...``\n      Commands and flags to supply to sphinx-apidoc. Note that some arguments\n      like `--dry-run` are ignored.\n\noptions:\n   -h, --help\n      show this help message and exit\n   -v, --verbose\n      Increase application verbosity. This option is repeatable and will\n      increase verbosity each time it is repeated. This option cannot be used\n      when -q/--quiet is used. (default: 3)\n   -q, --quiet\n      Disable logging. This option cannot be used when -v/--verbose is used.\n      (default: False)\n   --version\n      show program's version number and exit\n   -f, --force\n      Replace existing files. (default: False)\n   -n, --dry-run\n      Run the script without creating files (default: False)\n   -o, --output-dir\n      directory to place all output (default: None)\n   --package-name\n      Name of the directory to put the package documentation in. By default it\n      is the name of the package itself. (default: None)\n\n``sphinx-apidoc`` options:\n   -s, --suffix\n      file suffix (default: rst)\n   --implicit-namespaces\n      interpret module paths according to PEP-0420 implicit namespaces\n      specification (default: False)\n\nSphinx Extension Configuration\n++++++++++++++++++++++++++++++\n\nThe following configuration values are used:\n\n+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------+-------------------------+------------+\n| Option Name                                   | Description                                                                                                      | Default                 | Required?  |\n+===============================================+==================================================================================================================+=========================+============+\n| ``sphinx_nested_apidoc_package_dir``          | This is where the package to document resides.                                                                   |                         | **YES**    |\n+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------+-------------------------+------------+\n| ``sphinx_nested_apidoc_package_name``         | Name of the directory to put all the package documentation in. By default it is the name of the package itself.  | ``None``                |            |\n+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------+-------------------------+------------+\n| ``sphinx_nested_apidoc_suffix``               | The suffix of the generated documentation files.                                                                 | ``rst``                 |            |\n+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------+-------------------------+------------+\n| ``sphinx_nested_apidoc_excluded_files``       | List of files (without extension) to exclude from modification/renaming.                                         | ``index``, ``modules``  |            |\n+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------+-------------------------+------------+\n| ``sphinx_nested_apidoc_module_first``         | put module documentation before submodule documentation.                                                         | ``False``               |            |\n+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------+-------------------------+------------+\n| ``sphinx_nested_apidoc_implicit_namespaces``  | interpret module paths according to PEP-0420 implicit namespaces specification.                                  | ``False``               |            |\n+-----------------------------------------------+------------------------------------------------------------------------------------------------------------------+-------------------------+------------+\n\nSome additional details\n+++++++++++++++++++++++\n\nWhat it does\n------------\n\n- As you saw earlier, it generates a nested directory from a flattened one.\n- Under the hood, it uses ``sphinx-apidoc``. More on this below.\n\nAs stated above, ``sphinx-nested-apidoc`` uses ``sphinx-apidoc`` internally.\nThis means, you can configure ``sphinx-apidoc`` from ``sphinx-nested-apidoc``.\nFor example:\n\n.. code-block:: bash\n\n   # You can pass arguments like this:\n   sphinx-nested-apidoc -o docs/ mymodule/ -- -M -F --ext-githubpages\n   # or you can simply omit the '--'.\n\nEverything after the required positional argument of ``sphinx-nested-apidoc``\nis passed to ``sphinx-apidoc``.\n\nWhat it does not do\n-------------------\n\n- It does not modify the contents of the file. It just renames (or moves) them.\n- It is not a standalone tool. It requires ``sphinx-apidoc`` for its work.\n\nLicense\n+++++++\n\n`MIT \u003chttps://choosealicense.com/licenses/mit/\u003e`_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farunanshub%2Fsphinx-nested-apidoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farunanshub%2Fsphinx-nested-apidoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farunanshub%2Fsphinx-nested-apidoc/lists"}