ansys / ansys/pyansys-dev-guide

Typehinting extensions proposed may not work

Open
#187 9 comments 2 reactions 0 assignees View on GitHub
documentation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.