ansys / ansys/pyansys-dev-guide
Typehinting extensions proposed may not work
- Dominant language
- No language data
- Stars
- 41
- Forks
- 9
- Avg merge
- 11h 24m
- Merged PRs (30d)
- 12
Description
### Description of the modifications
In [dev-guide](https://dev.docs.pyansys.com/doc-style/docstrings.html#type-hints), three extensions are presented in order to improve the documentation when using type hints.
However, in my case (pydpf-core and pydpf-post) the documentation was failing to build when including these extensions (following the appropriate order) in the conf.py file.
Instead, I've seen that other repos (pymapdl, pyfluent) use a different extension named "sphinx_autodoc_typehints", see their [documentation](https://pypi.org/project/sphinx-autodoc-typehints/). Note that the documentation states that when using this extension in conjunction with sphinx.ext.napoleon, sphinx.ext.napoleon should be loaded first, before sphinx_autodoc_typehints.
This approach seems to work for pydpf-core and pydpf-post.
### Useful links and references
- Current dev-guide recomentation on type hints: https://dev.docs.pyansys.com/doc-style/docstrings.html#type-hints
- sphinx_autodoc_typehints documentation: https://pypi.org/project/sphinx-autodoc-typehints/
Contributor guide
Research direction
Start with the dev-guide’s doc-style/type-hints section and the referenced conf.py extension setup. Compare the three proposed extensions with sphinx_autodoc_typehints and the loading order used by pymapdl, pyfluent, pydpf-core, and pydpf-post. Done means the guidance reflects a configuration that builds successfully in the affected repositories.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100