Add xtensor docs #1504

ricardoV94 · 2025-06-30T09:21:09Z

📚 Documentation preview 📚: https://pytensor--1504.org.readthedocs.build/en/1504/

OriolAbril

other than fixing the environment everything looks good, there are a couple other things that could be done but also feel free to merge with just fixing the environment

doc/environment.yml

OriolAbril · 2025-07-02T09:31:51Z

doc/conf.py

+        warnings.warn(f"Could not find source code for {domain}:{info}")
        filename = info["module"].replace(".", "/") + ".py"


Suggested change

warnings.warn(f"Could not find source code for {domain}:{info}")

filename = info["module"].replace(".", "/") + ".py"

filename = obj.__module__.replace(".", "/") + ".py"

I would not commit the warning, it is useful for debugging but objects that are instances of Ops like part of the pytensor.tensor.math module being an instance of Elemwise will end up here and I think it is fine.

Using obj.__module__ instead of info["module"] should always point to the file where things are implemented, not a potentially higher module where things are exposed and documented at. Example again from math module, log is exposed as pytensor.tensor.log and documented there, so info["module"] means the link points to pytensor/tensor.py whereas using obj.__module__ makes it point to pytensor/tensor/math.py

by obj you mean fn that would be returned by find_source?

oh, I didn't realize obj is only available within the function. I will take another look, we might need 3 levels of granularity:

try to get obj if works go ahead to 2, otherwise use info["module"]

try to get sourcefile and sourcelines, if works go to 3, otherwise use obj.__module__

Format sourcefile and line numbers into url.

I pushed some changes, can you check?

Not everything that was an object ended up having a module

(exception: 'wrapper_descriptor' object has no attribute '__module__') if I raise in the most nested except AttributeError now

This might be because of the wrappers, I will try if calling inspect.unwrap on obj like numpy does helps with some of these. In general looks good, and from the docs preview it looks like we are getting to the right lines or at least the right file

the unwrap doesn't seem to fix anything. But I think it is working well enough after your updates

doc/library/xtensor/index.md

doc/library/xtensor/module_functions.md

OriolAbril · 2025-07-02T10:37:28Z

doc/library/xtensor/type.md

+## XTensorVariable creation functions
+
+```{eval-rst}
+.. currentmodule:: pytensor.xtensor.type
+.. autosummary::
+   :toctree: generated/


similar to previous comment, I might remove the toctree generated (keep autosummary here though) so all the pages have the same look

What does autosummary do btw?

goes over provided inputs in order to define their API pages from templates. The templates use autodoc directives so it is a smallish layer on top of it that is often more convenient (e.g. allows to choose between everything embedded within the same page like pytensor has or object-specific pages all linked through the toctree like pymc has)

I tried not doing toctree generated, and listing members explicitly, but somehow the page is empty. Can you take a look?

Taking a look

ricardoV94 · 2025-07-02T14:56:30Z

We get a lot of Warning: document isn't included in any toctree. Do we care?

OriolAbril · 2025-07-02T15:01:58Z

We get a lot of Warning: document isn't included in any toctree. Do we care?

A lot of? For the pages we have added or other ones? This means those pages are not reachable through the navbar+sidebar navigation. Unless there are referenced in another page or the users magically know their url they won't be able to reach them. Ideally there wouldn't be toctree warnings, if we really want to have pages that are not on the toctree and are only referenced inline somewhere else they should include :orphan: in their frontmatter

Co-authored-by: Oriol Abril-Pla <oriol.abril.pla@gmail.com>

ricardoV94 · 2025-07-02T15:07:04Z

Okay not a lot:

/home/ricardo/Documents/pytensor/doc/README.md: WARNING: document isn't included in any toctree
/home/ricardo/Documents/pytensor/doc/library/misc/pkl_utils.rst: WARNING: document isn't included in any toctree
/home/ricardo/Documents/pytensor/doc/library/scalar/index.rst: WARNING: document isn't included in any toctree
/home/ricardo/Documents/pytensor/doc/library/sparse/sandbox.rst: WARNING: document isn't included in any toctree
/home/ricardo/Documents/pytensor/doc/library/tensor/random/distributions.rst: WARNING: document isn't included in any toctree
/home/ricardo/Documents/pytensor/doc/library/xtensor/generated/pytensor.xtensor.concat.rst: WARNING: document isn't included in any toctree
/home/ricardo/Documents/pytensor/doc/library/xtensor/generated/pytensor.xtensor.dot.rst: WARNING: document isn't included in any toctree
/home/ricardo/Documents/pytensor/doc/library/xtensor/generated/pytensor.xtensor.type.XTensorConstant.rst: WARNING: document isn't included in any toctree
/home/ricardo/Documents/pytensor/doc/library/xtensor/generated/pytensor.xtensor.type.XTensorType.rst: WARNING: document isn't included in any toctree
/home/ricardo/Documents/pytensor/doc/library/xtensor/generated/pytensor.xtensor.type.XTensorVariable.rst: WARNING: document isn't included in any toctree
/home/ricardo/Documents/pytensor/doc/library/xtensor/generated/pytensor.xtensor.type.as_xtensor.rst: WARNING: document isn't included in any toctree
/home/ricardo/Documents/pytensor/doc/library/xtensor/generated/pytensor.xtensor.type.xtensor.rst: WARNING: document isn't included in any toctree
/home/ricardo/Documents/pytensor/doc/library/xtensor/generated/pytensor.xtensor.type.xtensor_constant.rst: WARNING: document isn't included in any toctree

Some are the ones I removed that are tracked in #1512 the others are dot, concat which is odd, and the xtensor.type, that I mentioned is coming up blank

distributions.rst probably became an orphan earlier on. Mentioned on the issue

OriolAbril · 2025-07-02T15:30:03Z

The ones in the generated folder is because they were automatically generated by autosummary at some point when :toctree: generated/ was set, now that it is not used these should be removed. The readme we probably want to exclude from conf.py. And the rest we can track in the issue

ricardoV94 · 2025-07-02T15:31:53Z

If you are checking out the branch already feel free to push the removal of readme.md

codecov · 2025-07-02T15:52:15Z

Codecov Report

Attention: Patch coverage is 56.72131% with 132 lines in your changes missing coverage. Please review.

Project coverage is 81.82%. Comparing base (2ab60b3) to head (8ffa97e).
Report is 8 commits behind head on main.

Files with missing lines	Patch %	Lines
pytensor/xtensor/math.py	56.38%	0 Missing and 99 partials ⚠️
pytensor/xtensor/random.py	57.89%	0 Missing and 32 partials ⚠️
pytensor/xtensor/type.py	50.00%	1 Missing ⚠️

❌ Your patch check has failed because the patch coverage (56.72%) is below the target coverage (100.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1504      +/-   ##
==========================================
- Coverage   81.98%   81.82%   -0.16%     
==========================================
  Files         231      231              
  Lines       52274    52467     +193     
  Branches     9206     9338     +132     
==========================================
+ Hits        42856    42931      +75     
+ Misses       7106     7095      -11     
- Partials     2312     2441     +129

Files with missing lines	Coverage Δ
pytensor/xtensor/linalg.py	`86.66% <ø> (ø)`
pytensor/xtensor/shape.py	`77.85% <ø> (ø)`
pytensor/xtensor/type.py	`68.34% <50.00%> (ø)`
pytensor/xtensor/random.py	`66.66% <57.89%> (-23.21%)`	⬇️
pytensor/xtensor/math.py	`63.94% <56.38%> (-31.87%)`	⬇️

... and 4 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

OriolAbril · 2025-07-02T16:13:24Z

xtensor.type page fixed and README excluded. I spent most of the time being gaslighted by automodule telling me no-index wasn't valid, re-reading the docs, trying different characters for the hyphen, doing :no-index: true instead. The docs seem clear on that:

It was :noindex: with no hyphen at all 🤦🏿

ricardoV94 · 2025-07-02T16:50:01Z

That seems like a very fun afternoon xD

ricardoV94 added docs xtensor labels Jun 30, 2025

ricardoV94 force-pushed the xtensor_docs branch 3 times, most recently from a703ae4 to d472f62 Compare July 1, 2025 11:55

ricardoV94 requested a review from OriolAbril July 1, 2025 11:57

OriolAbril approved these changes Jul 2, 2025

View reviewed changes

ricardoV94 force-pushed the xtensor_docs branch from d472f62 to 4e825f7 Compare July 2, 2025 14:57

ricardoV94 force-pushed the xtensor_docs branch from 4e825f7 to 6939ee0 Compare July 2, 2025 15:02

ricardoV94 and others added 4 commits July 2, 2025 17:04

Remove poor docs from listing

70e9973

Fix docs source linking

f876f97

Co-authored-by: Oriol Abril-Pla <oriol.abril.pla@gmail.com>

Add copy code button

a43f6b8

Co-authored-by: Oriol Abril-Pla <oriol.abril.pla@gmail.com>

Add xtensor docs

158ee2a

Co-authored-by: Oriol Abril-Pla <oriol.abril.pla@gmail.com>

ricardoV94 force-pushed the xtensor_docs branch from 6939ee0 to 158ee2a Compare July 2, 2025 15:04

ricardoV94 marked this pull request as ready for review July 2, 2025 15:34

fix xtensor.type page and exclude README from build

8ffa97e

		warnings.warn(f"Could not find source code for {domain}:{info}")
		filename = info["module"].replace(".", "/") + ".py"

	warnings.warn(f"Could not find source code for {domain}:{info}")
	filename = info["module"].replace(".", "/") + ".py"
	filename = obj.__module__.replace(".", "/") + ".py"

Add xtensor docs #1504

Are you sure you want to change the base?

Add xtensor docs #1504

Uh oh!

Conversation

ricardoV94 commented Jun 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

OriolAbril left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ricardoV94 commented Jul 2, 2025

Uh oh!

OriolAbril commented Jul 2, 2025

Uh oh!

ricardoV94 commented Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

OriolAbril commented Jul 2, 2025

Uh oh!

ricardoV94 commented Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

OriolAbril commented Jul 2, 2025

Uh oh!

ricardoV94 commented Jul 2, 2025

Uh oh!

Uh oh!

ricardoV94 commented Jun 30, 2025 •

edited

Loading

ricardoV94 commented Jul 2, 2025 •

edited

Loading

ricardoV94 commented Jul 2, 2025 •

edited

Loading

codecov bot commented Jul 2, 2025 •

edited

Loading