5

I have multiple modules in my package.

package/
|--mod1.py
|--mod2.py

Each module contains some functions and a test_function for testing the module.

I am using sphinx-apidoc to generate the .rst files for every module in package. My problem is that when I am generating documentation for my package, the test functions are also getting included in the documentation. I know it is possible to skip functions by using: :exclude members: function. But I'm looking for a solution that will allow me to do that for all modules by using a pattern similar to test_*.

My package.rst file looks like this:

package package
===============

Submodules
----------

.. toctree::

   package.mod1
   package.mod2

Module contents
---------------

.. automodule:: package
    :members:
    :undoc-members:
    :show-inheritance:

And my mod1.rst file looks like this:

package.mod1 module
===================

.. automodule:: package.mod1
    :members:
    :undoc-members:
    :show-inheritance:

Thanks in advance.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Shubham Vasaikar
  • 698
  • 9
  • 23
  • Normally, your tests would go under a `test` or `tests` directory, then you can exclude the entire directory. – loganasherjones Aug 31 '16 at 12:20
  • @L-Jones9 Yes but it would be too much work to move all test to a different directory at this point of time. Thanks a lot though, I'll consider it in the future. – Shubham Vasaikar Aug 31 '16 at 12:23
  • 3
    You can skip the functions whose names start with "test_" by defining a handler (a function in conf.py) that returns `True` when invoked from the `autodoc-skip-member` event. See http://www.sphinx-doc.org/en/stable/ext/autodoc.html#event-autodoc-skip-member. – mzjn Aug 31 '16 at 14:34

1 Answers1

9

While @mzjn's comment was definitely a good pointer, I still struggled with that for a while.

The solution is to write a handler for the autodoc-skip-member event and connect it to the autodoc-skip-member event, in the conf.py file.

So here is how the latter will look like:

# conf.py

# Loads of configuration settings

# This is the expected signature of the handler for this event, cf doc
def autodoc_skip_member_handler(app, what, name, obj, skip, options):
    # Basic approach; you might want a regex instead
    return name.startswith("test_")

# Automatically called by sphinx at startup
def setup(app):
    # Connect the autodoc-skip-member event from apidoc to the callback
    app.connect('autodoc-skip-member', autodoc_skip_member_handler)
Right leg
  • 16,080
  • 7
  • 48
  • 81
  • I set my `autodoc_skip_member_handler` method to `return True` for every file and my setup still hangs. – NuclearPeon Jun 04 '20 at 21:41
  • @NuclearPeon It hangs, like it runs forever? That doesn't really look related... Maybe you could add a `print(name)` in the `autodoc_skip_member_handler` function to see how it's called? – Right leg Jun 04 '20 at 21:48
  • I printed out every attribute and I can see it going by. There's a file with a module-level command to connect to a database so everytime it reaches that point it hangs. I've tried ignoring the method call name, the containing module, the containing module's module, I've tried returning True and False immediately so it would skip everything, but it still hangs. May be a bug in sphinx. – NuclearPeon Jun 04 '20 at 21:56
  • This is the lead I got that directed me to the source of the hang. https://stackoverflow.com/questions/37818923/running-sphinx-html-make-gets-stuck-after-reading-sources – NuclearPeon Jun 04 '20 at 21:58