sphinx-doc / sphinx-doc/sphinx-argparse
doc generation failing due to typing imports
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 38
- Forks
- 33
- PR merge metrics
- No merged PRs in 30d
Description
When building docs with an sphinx-argparse directive, the following error occurs.
[...]
File "/home/francis/dev/miniconda/envs/weaver-py3/lib/python3.7/site-packages/sphinxarg/ext.py", line 474, in run
exec(code, mod)
File "../weaver/cli.py", line 28, in <module>
from weaver.typedefs import CWL, HeadersType, JSON
File "/home/francis/dev/weaver/weaver/typedefs.py", line 34, in <module>
from weaver.processes.wps_process_base import WpsProcessInterface
File "/home/francis/dev/weaver/weaver/processes/wps_process_base.py", line 17, in <module>
from weaver.typedefs import CWL_RuntimeInputsMap
ImportError: cannot import name 'CWL_RuntimeInputsMap' from 'weaver.typedefs' (/home/francis/dev/weaver/weaver/typedefs.py)
where my directive is as follows:
.. argparse::
:module: weaver.cli
:func: make_parser
:prog: weaver
The encountered error happens due to a typing import.
In the weaver.cli module, there is this in the imports:
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from weaver.typedefs import CWL, HeadersType, JSON
Because this is within a typing-enabled block, it should be ignored for "normal" execution.
Only typing parsers/linters must consider those imports, which I believe arparse shouldn't consider.
Note, this might be caused by interactions with package sphinx_autodoc_typehints which uses those typings during documentation generation. I'm not familiar enough with the internals of sphinx building to know if sphinx-argparse could disable typings only for its own context build.
Contributor guide
No contributing guide indexed for this repository
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
Reproduce the documentation build using the sphinx-argparse directive for weaver.cli.make_parser, then inspect weaver/cli.py, weaver/typedefs.py, and weaver/processes/wps_process_base.py around the TYPE_CHECKING imports and reported circular import. Check the interaction with sphinx_autodoc_typehints; done means the directive builds without the reported ImportError while preserving the intended typing-only imports.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100