Add core typing to documentation

[user27182]

Overview

Add documentation for the type definitions in core._typing_core.

Specifically:

1. Publish the types in the docs in Core API -> Typing

2. Make the _typing_core types in docstrings and annotations automatically linkable.

   • Example issue: the docs for set_array have a data : Array parameter in the docstring, but it is not linkable. This makes it unclear what is meant by Array.
   • This is accomplished by adding core types to the pyvista namespace. This is so that adding the types to the docs with just the type name (e.g. Vector will mean that sphinx will implictly find and link it automatically (no need to explicitly reference pyvista.core._typing_core.Vector)

3. Make the _typing_core annotations in function signatures more readable.

   • Example issue: since aliases are automatically expanded by sphinx, the annotations for array-like types can take up to 8 lines for a single parameter. See screenshot in Rename and Simplify validation package #5571 (comment)

The additions in this PR are similar to the configuration for ColorLike, which is a pyvista type alias that is linkable and is defined formally the docs. (See the color param for ChartBox as an example of its use in docstrings).

[tkoyama010]

LGTM

[user27182]

I wasn't sure how to document these. @darikg do you have a suggestion for these?

[user27182]

Thanks for the fixes and quick approval!

Might be good to do a manual check before this is merged. The aliases need from __future__ import annotations to be documented properly by sphinx. But this is only defined in _aliases, whereas the __doc__s are added in __init__.

So, I'm not sure if sphinx will actually pick up the docstrings correctly or not. I'm also curious to see how the TypeVar will appear in the docs.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.52%. Comparing base (234023c) to head (d639473).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5621      +/-   ##
==========================================
- Coverage   96.54%   96.52%   -0.02%     
==========================================
  Files         137      137              
  Lines       23301    23311      +10     
==========================================
+ Hits        22495    22500       +5     
- Misses        806      811       +5     

[tkoyama010]

Thanks. I will check in my local. It would be nice if we could do a preview build, but that mechanism is being rebuilt in #5360.

[user27182]

I have not been able to review the docs locally. The docs are approx 3.5GB in size, and download speeds seem to be capped at 500KB/sec, which means downloading them takes approx 2 hours. For some reason, the download keeps failing for me part way through and I have to re-retry. The download has failed 4 times for me already, not sure if that's just my machine or my web browser.

[tkoyama010]

I have not been able to review the docs locally. The docs are approx 3.5GB in size, and download speeds seem to be capped at 500KB/sec, which means downloading them takes approx 2 hours. For some reason, the download keeps failing for me part way through and I have to re-retry. The download has failed 4 times for me already, not sure if that's just my machine or my web browser.

The volume of documentation is bloated and is straining our development efficiency. This is a significant problem. We are discussing it in #5352 and would appreciate any ideas you may have.

[user27182]

I still can't download the docs locally for review 😔, not sure what the issue is or if there are any workarounds...

[tkoyama010]

github-actions preview

[tkoyama010]

github-actions preview

[github-actions]

🚀 Deployed on https://65d1e17a91a5a723b3ec9543--meek-duckanoo-d2f5ec.netlify.app

[tkoyama010]

🚀 Deployed on https://65d1e17a91a5a723b3ec9543--meek-duckanoo-d2f5ec.netlify.app

Preview is deployed. Let's review!

[user27182]

thank you🙏 that tool is very convenient

Some of the docstrings didn't show, and the aliases were still expanded, hopefully fixed now

[github-actions]

🚀 Deployed on https://65d830adf48efa981506a497--meek-duckanoo-d2f5ec.netlify.app

[user27182]

Deployed on https://65d830adf48efa981506a497--meek-duckanoo-d2f5ec.netlify.app

It looks like the links are no longer working alias is now expanded again in datasetattributes.set_array. I suspect this may be from 5dbc9bc, which removed the from __future__ import annotations statement. This could mean that it may be necessary to add that line to every file where the alias is used.

[user27182]

github-actions preview

[github-actions]

🚀 Deployed on https://65d9097e1d98156ae7d89bd8--meek-duckanoo-d2f5ec.netlify.app

[user27182]

🚀 Deployed on https://65d9097e1d98156ae7d89bd8--meek-duckanoo-d2f5ec.netlify.app

The alias in the set_array function signature is now correctly set as ArrayLike.

The alias in signature is not linked, however. This seems to be a bug, with a possible workaround here.
sphinx-doc/sphinx#10785

[user27182]

The alias in the set_array function signature is now correctly set as ArrayLike.

This confirms that it may be (or is likely) necessary to add from __future__ import annotations to every file where we want the alias to display correctly in the docs...

[user27182]

github-actions preview

[github-actions]

🚀 Deployed on https://65d951a0b791cd8a5fda3017--meek-duckanoo-d2f5ec.netlify.app

[user27182]

This PR looks good to me.

I am a bit concerned that some references to ArrayLike might not get picked up correctly in the future for modules that will import ArrayLike. But, this issue likely applies to ColorLike as well. So,I think maybe a separate PR can work to resolve that if or when that happens.

[tkoyama010]

LGTM. Thanks!

[tkoyama010]

Please wait while we merge #5670 first.

[user27182]

I am a bit concerned that some references to ArrayLike might not get picked up correctly in the future for modules that will import ArrayLike. But, this issue likely applies to ColorLike as well. So,I think maybe a separate PR can work to resolve that if or when that happens.

Unfortunately, this issue has surfaced. Looking at the docs published here before this PR was merged,
https://65d951a0b791cd8a5fda3017--meek-duckanoo-d2f5ec.netlify.app/api/core/_autosummary/pyvista.polydata

we see that PolyData's array-like aliases are expanded.

[user27182]

I wonder if @dcbr can help.

This PR added ArrayLike aliases to the docs, similar to what was done for ColorLike in #2175.
But, we are having issues where it seems that from __future__ import annotations may need to be added to every file where we want the alias to display correctly in the docs. Ideally we wouldn't need to do this.

If we look at the docs for ChartBox, it has a working ColorLike alias in the parameters. And, looking at the source code, I see that charts.py does not have a the from future import statement.

Do you know how this was achieved?
Not sure if there's a trick with how the alases are imported, or a config hack that was missed by this PR (but is part of #2175).

[dcbr]

It's been a while since I messed with those aliases, I know it was a lot of trial and error and don't remember the exact "solution"; but I will try to have another look and see if I can help resolve it.

[user27182]

It's been a while since I messed with those aliases, I know it was a lot of trial and error and don't remember the exact "solution"; but I will try to have another look and see if I can help resolve it.

Thanks, this PR tried to copy the same config, and there was also lots of trial and error. A possible source of the issue may be from:

1. differences in how the aliases are defined and imported into the pyvista namespace
   • ColorLike gets imported lazily (like many plotting objects), whereas ArrayLike gets imported explicitly via core._typing_core.__init__
   • This may be relevant since from __future__ import annotations is definitely needed in the modules where the aliases are defined, so maybe the import messes with this somehow
2. the plotting._typing modules imports these explicitly while TYPE_CHECKING:

   pyvista/pyvista/plotting/_typing.py

   Lines 11 to 13 in e338c17

   	if TYPE_CHECKING: # pragma: no cover
   	from .plotting.charts import Chart2D, ChartBox, ChartMPL, ChartPie
   	from .plotting.colors import Color

   • These imported modules use ColorLike, so perhaps that's what allows the docs to recognize the aliases
   • The ArrayLike modules do not have this kind of import

After writing this, I strongly suspect that # 2 is the issue, and that adding a conditional TYPE_CHECKING import for any/all modules which may use the ArrayLike aliases may fix this.

[dcbr]

Sorry, I haven't had much time lately, so I haven't properly looked into this yet.
But another difference I noticed is the way the documentation for the type alias is generated here. For ColorLike it is generated using .. autosummary:: (see utilities.rst). I'm not at all a Sphinx expert, so maybe these are equivalent, but maybe you can give this a try?
Additionally, I don't see this typing module being documented on the deployed documentation for the 'dev' branch?