Documentation should be generated with `typing.TYPE_CHECKING == True`
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.2k
- Forks
- 146
- PR merge metrics
- No merged PRs in 30d
Description
TL;DR
pdoc should set typing.TYPE_CHECKING to True.
Long Read
I was investigating a root cause of #459, and to apply the workaround, I added an import within the if (typing.TYPE_CHECKING) condition.
However, this didn't work, and it forced me to extract the import in question outside of the if statement. Then I've searched for the TYPE_CHECKING in the entire source tree, and found only two occurrences inside _version.py.
Enabling this will allow "heavy" or otherwise not needed imports to occur, and thus will allow proper linking between the modules.
Looks like this is an easy fix, and the flag should be set before generating the modules' documentation, probably in pdoc.Module class or in cli.main.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by inspecting the pdoc.Module class and cli.main, which the issue identifies as likely locations for setting typing.TYPE_CHECKING before documentation generation. Check how modules are loaded and document the behavior with a focused test or reproduction showing that TYPE_CHECKING imports are available for linking.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100