pdoc3 / pdoc

:snake: :arrow_right: :scroll: Auto-generate API documentation for Python projects
https://pdoc3.github.io/pdoc/
GNU Affero General Public License v3.0
1.12k stars 145 forks source link

Unable to configure pdoc3 to ignore tests directory #368

Closed gvwilson closed 9 months ago

gvwilson commented 2 years ago

I want pdoc3 to skip everything in my project's the tests directory, but even after reading #99 I am unable to get it to do so. Steps taken:

"""Main program."""

def main(): pass
"""Test code."""

def test(): pass
$ tree --charset unicode html
html
`-- mwe
    |-- index.html
    |-- main.html
    `-- tests
        |-- index.html
        `-- test.html
/Users/gvwilson/miniforge3/lib/python3.9/site-packages/pdoc/__init__.py:239: UserWarning: Couldn't read PEP-224 variable docstrings from <Module 'mwe.tests'>: could not get source code
  warn("Couldn't read PEP-224 variable docstrings from {!r}: {}".format(doc_obj, exc))
__pdoc__ = {
    'tests': False
}

produces a different error message:

/Users/gvwilson/miniforge3/lib/python3.9/site-packages/pdoc/__init__.py:706: UserWarning: __pdoc__-overriden key 'tests' does not exist in module 'mwe.tests'
  warn('__pdoc__-overriden key {!r} does not exist '
__pdoc__ = {
    'tests': False
}
__pdoc__ = {
    'mwe.tests': False
}

I'd be grateful for the correct incantation (or if one doesn't exist, I'd be happy to PR a --ignore dir [dir] option).

kernc commented 2 years ago

The first "error message" is just a warning; CPython issue bpo27578, PR https://github.com/python/cpython/pull/20809 (please upvote).

__pdoc__ = {'tests': False} inside mwe.tests is obviously wrong (results in the path mwe.tests.tests). But __pdoc__ = {'tests': False} in the main mwe/__init__.py absoltely should work. If it doesn't, it might be a bug related to https://github.com/pdoc3/pdoc/issues/306 or some other issue. :grimacing: If you would take the time to investigate it, that would certainly be appreciated! :sweat_smile:

Another workaround that might work is to prefix tests dir with an underscore (i.e. _tests).