typing.TYPE_CHECKING conditional imports break sphinx doc generation #22
Comments
|
Aside from the fact that your example isn't valid Python syntax, what do you expect me to do? I could only think of setting |
|
Your repository contains a circular import. I don't see how it could work even if |
|
I have created a repository with a fully working example and step by step instructions on how to reproduce the error. https://github.com/henryJack/sphinx_issue/blob/master/README.md The module in question is here https://github.com/henryJack/sphinx_issue/tree/master/mymodule. Yes, it does contain a circular import (which can happen when you introduce python 3.5 type hinting into the mix). The code is still valid python without it though |
|
But what do you expect me to do about this? As I just said, forcing |
|
Good discussion here on how typing can lead to circular imports: python/typing#105... The issue is that everything works up until the point you add the |
|
Well, fix the circular import. Then you won't even need the |
|
It should be changed so that string type annotations should never get evaluated. Python runs this just fine... from typing import TYPE_CHECKING class AClass: |
|
Circular imports for type checking are valid, they don't need to be fixed |
|
You're talking about static typechecking here. Libraries that get type information at run time, like this extension, need to resolve them properly via imports. |
|
This is necessary in order to generate the links to the appropriate sections of the API documentation. |
|
Wouldn't it be better though if offending types are just ignored and displayed as strings and not links. Currently, it breaks the whole make docs process. It's a great library and I would still like to use it |
|
Yes, that would be an acceptable fix. I'm just wondering if it should generate some kind of warning too, so as not to hide any problems. |
|
Ideally, A warning + unlinked string would be great. This other example would also break the sphinx build and is 100% valid python class Assembly:
def __init__(self) -> None:
self.sub_assemblies: List['Assembly'] = None |
|
As far I can tell, the code for |
|
That last example would not break this extension because it only looks at function level annotations. |
|
Here is the code you'll want to look at. |
|
Firstly, thank you agronholm for your work on this module. The current PR seems like a reasonable first fix, and it would be nice to see it merged, but I had the beginnings of another idea. Might it be possible to perform two passes? On the first pass TYPE_CHECKING is False, and on the second True. No circular imports would occur on the second try since the relevant modules would have already executed all the way through and be in sys.modules. Thoughts? |
- Also add autodoc typing plugin to make typing hints documentation just slightly better. A side effect of agronholm/sphinx-autodoc-typehints#22 is that we have to remove typing hints for circular imports
Summary: sphinx-autodoc-typehints (https://github.com/agronholm/sphinx-autodoc-typehints) isn't happy with importing specific classes within the conditional type checking statement (used to avoid circular dependencies). See https://github.com/agronholm/sphinx-autodoc-typehints/issues/22 for this issue. The way to get around this, following https://github.com/agronholm/sphinx-autodoc-typehints#dealing-with-circular-imports and discussion on GitHub issue, is to import the module. I had to go two levels up often and import top-level modules in order for this to all work properly. Reviewed By: ldworkin Differential Revision: D14400529 fbshipit-source-id: 5cb726201072aa6084e2a918dadffefcd1b15afc
|
I have just ran into this issue - similar to the closed MR from MyST-Parser. When is this going to get fixed? |
|
A PR for this would we welcome. |
|
I recently bumped into this issue in other projects too. The problem here is that any |
Smart suggestion. For the memo, I've given a try with it on my own project (I shall update this reply with a link to it later). In the end, I bet a better approach would be to switch to static analysis of the code (as mypy does) to extract documentation from it. I just came to know about sphinx-extensions2/sphinx-autodoc2, which claims something around this topic. |
Hi,
I've created a dummy repo highlighting my issue. There is a python module called
mymoduleand aREADME.mdexplaining my full step by step issue...https://github.com/henryJack/sphinx_issue/blob/master/README.md
Problem
sphinx-autodoc-typehintsextension with python 3.5+ typings It fails to build. The error meesage is:Procedure to reproduce the problem
Please see https://github.com/henryJack/sphinx_issue/blob/master/README.md
Basically, the problem lies in declaring imports using TYPE_CHECKING
Error logs / results
Expected results
It breaks the docs generator.
Environment info
The text was updated successfully, but these errors were encountered: