A user tool to debug visibility of objects - #522
Conversation
75f2024 to
3ac44d8
Compare
AWhetter
left a comment
AWhetter
left a comment
There was a problem hiding this comment.
This is a great idea! Thanks for making the change. I've left some comments for improvements.
| app.add_config_value("autoapi_generate_api_docs", True, "html") | ||
| app.add_config_value("autoapi_prepare_jinja_env", None, "html") | ||
| app.add_config_value("autoapi_own_page_level", "module", "html") | ||
| app.add_config_value("autoapi_verbose_visibility", 0, "html") |
There was a problem hiding this comment.
Could we utilise logging levels instead of needing to invent our own way of configuring verbosity?
There was a problem hiding this comment.
Yep. I was just worrying about not changing the current logging behaviour too much!
There was a problem hiding this comment.
Actually, looking at this again, it adds way too much output to debug mode. I think it makes sense to have this separate for debugging visibility. Also I split the visibility debugging into two verbosity levels as usually level 1 will suffice, but allowing for deeper debugging,.
There was a problem hiding this comment.
In which case please can you add some documentation for this new config option to docs/reference/config.rst. You could also add a small section about debugging to docs/how_to.rst, possibly as a subsection to "How to Customise What Gets Documented", or linking to your new section from there.
| _trace_visibility(self.app, f"Testing if any children of {module['full_name']} have already been documented") | ||
| for child in module["children"]: | ||
| if "original_path" in child: | ||
| _trace_visibility(self.app, f"Hiding {child['full_name']} as documented at {child['original_path']}") |
There was a problem hiding this comment.
These items are hidden not because they're documented elsewhere (in fact they may not be documented anywhere) because we don't consider objects imported from the local package into a module to be part of the public API. Usually those imports are used in the implementation of a class or function in that module instead.
There was a problem hiding this comment.
ah, makes sense. I think this caught me out because i use import to populate init, and i wasn't getting documentation because the module had no top level documentation - i.e. the fix was to add a docstring at the top of init. Is this something that should be added to the docs?
There was a problem hiding this comment.
Does https://sphinx-autoapi.readthedocs.io/en/latest/how_to.html#how-to-customise-what-gets-documented
cover what you're thinking about?
Thank you, glad this is appreciated! One question I have - with the 'hide reason' enum idea, we could use this in autoapi-skip-member interface. Do you think it would make sense to add this to that api? |
4fc088f to
9c8d0a2
Compare
|
I'm having some odd issues running the tests in |
Good point. If we use an enum then someone can't extend that enum easily to add their own reasons for something being skipped. Perhaps letting |
|
Yep, the enum is a string enum already , so exposing as a string makes most
sense.
…On Thu, 5 Jun 2025 at 16:10, Ashley Whetter ***@***.***> wrote:
*AWhetter* left a comment (readthedocs/sphinx-autoapi#522)
<#522 (comment)>
One question I have - with the 'hide reason' enum idea, we could use this
in autoapi-skip-member interface. Do you think it would make sense to add
this to that api?
Good point. If we use an enum then someone can't extend that enum easily
to add their own reasons for something being skipped. Perhaps letting
autoapi-skip-member return a string (with the return type bool | str |
None) would be best. What do you think?
—
Reply to this email directly, view it on GitHub
<#522 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAB4O4FCPF2K7COGG2EGVBT3CBMVVAVCNFSM6AAAAAB4SOQBBGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSNBUHEZTEOBQGM>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
Fix the display property to use the cached hide_reason instead of recomputing it, and only trace on cache-hit when the object is actually hidden. Add documentation for autoapi_verbose_visibility in config.rst and a debugging guide in how_to.rst. Co-developed-by: Claude Code v2.1.131 (claude-opus-4-7)
Add a note under the autoapi_options section explaining that packages without a module-level docstring in __init__.py are excluded when undoc-members is not enabled. Co-developed-by: Claude Code v2.1.131 (claude-opus-4-7)
|
Hi @AWhetter, I've pushed two new commits addressing your feedback: 1. Fixed the
2. Added documentation (
3. Documented the
Re your question about |
2 participants
It seems users can get quite disoriented when switching off "undoc-members" - whole modules will stop rendering even though there may be documented objects within.
This PR adds a config that helps users to debug why items may not be rendering, and also adds an info log for the common case of the module itself missing top level documentation in init.py
Interested in your thoughts!