0

I'm developing a Python package that allows users to import its functions like this:

import mymodule
mymodule.afunction()

I'm documenting the code with sphinx. I first ran sphinx-quickstart, then I changed conf.py to include sys.path.insert(0, os.path.abspath(‘../../src/mymodule’)). Then I ran sphinx-apidoc -f -o source ../src/mymodule and make html. The directory structure is like this:

├── doc
│   ├── Makefile
│   ├── build
│   ├── make.bat
│   └── source
│       ├── _static
│       ├── _templates
│       ├── conf.py
│       ├── index.rst
│       ├── modules.rst
│       └── mymodule.rst
└── src
    └── mymodule
        ├── __init__.py
        └── modulecode.py

The output lists a "mymodule.modulecode" submodule. But because of my __init__py, users don't explicitly import modulecode.

enter image description here

Is there an automated way of making the sphinx documentation list the function mymodule.afunction() (which is accessed by the user), instead of mymodule.modulecode.afunction() (which the user doesn't call)?

mzjn
  • 48,958
  • 13
  • 128
  • 248
Danny
  • 35
  • 4
  • 1
    Similar questions: https://stackoverflow.com/q/15115514/407651. https://stackoverflow.com/q/47903710/407651 – mzjn Jan 05 '22 at 19:29
  • Thanks for posting the links! I hadn't seen them; I must have used ineffective search terms when I looked earlier. – Danny Jan 05 '22 at 20:28
  • Guided by the above links, I was able to solve the issue. I needed two steps: (1) Add \_\_all\_\_ to \_\_init\_\_.py, as discussed in https://stackoverflow.com/q/15115514/407651. (2) Delete the submodule section from modules.rst. I don't think the other posts explicitly mention that apidoc might be adding an submodules section that can safely be deleted. Later today, I might write an answer to this question that adds this info. (But if anyone has reasons why that's not worth posting an answer for, that's OK too!) – Danny Jan 05 '22 at 20:33
  • Note to anyone reading this later: Step 2 should say "mymodule.rst", NOT "modules.rst". – Danny Jan 06 '22 at 03:49

1 Answers1

1

Thanks to mzjn for the helpful comments on my original question! As discussed in the comments, I needed to do 2 things:

  1. Add __all__=[list of defined functions] to my __init__.py
  2. Delete the entire mymodule.modulecode module section from mymodule.rst.
Danny
  • 35
  • 4