3

I use sphinx-click extension for my click application, and i want to use sphinx-apidoc to generate .rst files for only submodules.

I've been working with pythons Sphinx documentation library for about a year now, and I have a usecase... I cannot quite figure out.. maybe I'm just blind right now.

Anyways, I have a cli tool structured something like

my_tool/
+-- __init__.py
+-- cli_entry.py
+-- utils
|   +-- __init__.py
|   +-- foo.py
|   +-- bar.py

Where cli_entry is a click application, and it imports my_tool.utils.foo and my_tools.utils.bar Since this is using the Click library. I've decided to use the sphinx_click extension to document any command that is in cli_entry.py (which documents all the commands great).

But heres the issue, I want to use sphinx-apidoc to generate the .rst files for everything that is in the ./my_tool/utils/ modules. When I use the command as sphinx-apidoc -o ../docs/utils my_tool/utils the output files that I get include

docs/
+-- utils
|   +-- module.rst
|   +-- utils.rst

Which looks great at first, but upon opening utils.rst the file looks something like

utils package
=============

Submodules
----------

utils.foo module
----------------------

.. automodule:: utils.foo
   :members:
   :undoc-members:
   :show-inheritance:

utils.bar module
----------------------

.. automodule:: utils.bar
   :members:
   :undoc-members:
   :show-inheritance:

Then when I build the documentation using make html (from sphinx generated makefile) I get an error saying Failed to import 'utils.foo': no module named utils.foo thats because the import should exist as my_tool.utils.foo

How can I use sphinx-apidoc to generate only submodules and include the correct import paths?? Maybe its something I'm missing in the conf.py.. maybe it's an option I'm missing from sphinx-apidoc?

EDIT: I should mention that I could use the exclude_pattern argument... but I would prefer to not have to specify each cli file in my root. ex. In the case that I have cli_entry.py, cli_commandgroup1.py... cli_commandgroupN.py. I want this solution to be dynamic enough to just support only submodules.

EDIT: I tried using sphinx-apidoc -o ../docs/utils my_tool/ and this creates the following output

docs/
+-- utils
|   +-- module.rst
|   +-- my_tool.cli_entry.rst
|   +-- my_tool.utils.rst

Now in the my_tool.utils.rst file, the imports are correct, and the docs can be generated.

my_tool.utils.foo module
----------------------

.. automodule:: my_tool.utils.foo
   :members:
   :undoc-members:
   :show-inheritance:

The issue with specifying my_tool/ is that my_tool.cli_entry.rst gets created, when this .rst file would already be created using the click-sphinx extension.

M.M
  • 51
  • 3
  • Note that you don't have to use sphinx-apidoc. You can write the needed RST markup yourself to ensure that only specific modules get documented. See also https://stackoverflow.com/a/28481785/407651. – mzjn Mar 19 '21 at 06:49
  • What does utils.rst look like if you run `sphinx-apidoc -o ../docs/utils my_tool/`? – mzjn Mar 19 '21 at 07:26
  • @mzjn, I would prefer to not need to write and maintain the RST files, and would like to rely the generation of RST files from sphinx-apidoc. If i use `sphinx-apidoc -o ../docs/utils my_tool/` Everything gets documented correctly. I'll update my post to share why this will not work. – M.M Mar 19 '21 at 16:22
  • OK. I don't think there is a way to use sphinx-apidoc for your particular use case that does not require some post-processing (removing and/or editing generated RST files). – mzjn Mar 19 '21 at 17:16
  • @mzjn thats what I was afraid of. Thanks for sharing – M.M Mar 19 '21 at 17:44

0 Answers0