sphinx-doc / sphinx-doc/sphinx-argparse

doc generation failing due to typing imports

Open
#7 0 comments 0 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.