Open castlez opened 1 month ago
Just confirmed that pinning sphinx-autoapi to version 3.1.0 solves the issue, meaning it was indeed something (somehow) in the 3.1.1 release. Looking at the code, i dont know enough to be able to pin point it, but im more confident its in there somewhere now. Gonna update the issue title to reflect that
This just started happening to me too recently. It seems like the issue is that build_finished
tries to delete the autoapi_root
here
https://github.com/readthedocs/sphinx-autoapi/blob/8001fbd6d80492253eb0dd8ef7753f9adf21fc57/autoapi/extension.py#L149-L159
but it fails, since the folder does not exist on my system, not sure why. I've worked around it by adding this to conf.py
autoapi_keep_files = True
but it would be nice to know why this started happening and what's wrong in my config :\
I just ran into the same issue, here's what I found:
I believe the autoapi_options
that is causing all this fuss is "undoc-members"
. It is present in the default value but if you remove it sphinx-autoapi doesn't produce rst files for anything "undocumented".
The short answer is: every module needs a docstring.
file.py
but no "module" docstring, nothing from that file will show up.file.py
has a module docstring but lives inside a package whose __init__.py
doesn't have a module docstring, nothing will show up.So for something to be documented by autoapi, all of his parents need to be documented and they must all have module docstrings. So in the project below, for anything from schema_one.py to show up, you will need to have docstrings as follows:
doc_test_project/
├── another_module.py
├── cli.py
├── __init__.py <-- Module docstring
└── schemas
├── __init__.py <-- Module docstring
└── schema_one.py <-- Document function + module
Either add module docstrings everywhere (or find some other solution to force autoapi to document these files) or add the "undoc-members"
option back into the autoapi_options
list
From a code point of view, I'm still trying to trace down the origin of the problem but I think the problem stems from here: https://github.com/readthedocs/sphinx-autoapi/blob/8001fbd6d80492253eb0dd8ef7753f9adf21fc57/autoapi/_mapper.py#L337-L343
I think due to the parameters, self.objects_to_render.items()
ends up being empty.
This seems to be caused by https://github.com/readthedocs/sphinx-autoapi/blob/eecb6e892aeefce249f46b90b49ccab3dd37133c/autoapi/_objects.py#L222-L242
returning True
for everything.
I would expect even modules without a top-level module docstring should still be documented by autoapi.
@alexfikl (Tagged you since it might answer your question)
Let me know if that helps!
@sachahu1 Can confirm that adding back undoc-members
to autoapi_options
fixes this for me. Thank you for the explanation!
I think that it's legitimate for a module with no docstring to not get rendered unless undoc-members
is set. undoc-members
can be a useful control for what gets documented and what doesn't, and this functionality should extend to modules as well.
It's not great that this behaviour changed in a minor release though. It probably warranted a major release, so apologies for the disruption caused.
As for this error, it seems to come up when no module is documented and index injection occurs. AutoAPI should raise a more friendly error or warning in this case.
This is new as of today, i have a build from yesterday that built the docs ok. Ive mentioned this in https://github.com/readthedocs/sphinx-autoapi/issues/441 but ill reiterate here for completeness.
Just another data point here, i get the same thing if i run in a venv but not if i use system python (granted i still get an error, but i think its unrelated to this issue)
versions:
Here's installing deps:
Here's the commands
and lastly here's the conf.py
Here's the output, this was not happening yesterday before this went in https://github.com/readthedocs/sphinx-autoapi/commit/eecb6e892aeefce249f46b90b49ccab3dd37133c (I am not 100% confident this change made it happen, i just see a correlation between this going in and this issue)
For what its worth, i have been using sphinx-autoapi for a while now, and only recently started seeing this. Hard to pinpoint because i dont redeploy docs everyday, but definitely in the last month this came up.
Not sure why its looking in
docs/source/autoapi/index.rst
thats never where the index has been