-
Notifications
You must be signed in to change notification settings - Fork 49
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
How to properly escape *
and _
when rendering docs with Sphinx
#203
Comments
Ok, nevermind, the not all was caused by the fact that I use |
Ah, that's good to know! For what it's worth (That aside, if this is a greenfield project then having tried both Sphinx and MkDocs, I've come to really enjoy the greater simplicity of the latter, and would recommend it!) |
I actually run in a problem where not solution is optimal because of that. Because I use this library, I cannot use When Sphinx's autodoc tries to import the module, it first tries with if TYPE_CHECKING:
from some_optioal_deps import ReturnType
else:
ReturnType = Any but will fail ( So the solution I came up with is try:
from some_optioal_deps import ReturnType
except ImportError:
ReturnType = Any which renders correctly in the docs (because I installed the optional deps to build the docs). However, tools like Pyright will complain because My current solution was to annotate each return type with I think you could "fix" this issue by removing imports to NumPy load, and only import this when needed. Anything, I thought it was interesting to document this here! |
Hello,
I use your great package to annotate all my functions, both for type checking and documentation purposes.
However, most Python package rely on
.rst
formatting, and do I, as a result of using Sphinx when generating the docs (I know I could opt for a Markdown parser, but not sure if that would solve my problem).Stars
*
are very common in my type annotation and some (not all, ?) signatures emit this warning when I build the docs::1: (WARNING/2) Inline emphasis start-string without end-string.
This is because, I think, RST tries to interpret
*
as the start of some markup, see result below.Above, the
*
links to some non-existing id.I have tried to define a custom Sphinx pre-processor to escape
*
to\*
, but it seems quite complex for such a seemingly stupid problem...Have you already encountered this problem and, if so, do you have any suggestion on how to solve this?
The text was updated successfully, but these errors were encountered: