How can we make docs better?

[ricardoV94]

The goal of this thread is to collect ideas on how we can make PyTensor docs better.

Suggestions more than welcome

[ricardoV94]

Add sections for different use cases?

• I want to use this library directly for (should I even bother?):

  • Performant code + autodiff
  • Graph features
  • Multi-backend support
  • Math simplification/ reasoning

• Some library I actually care about relies on PyTensor:

  • I guess this is the point I have to know what's under the hood
  • Should I just wrap my existing code in an Op and call it a day?
  • How to debug stuff?

• I'm a developer

  • (There's already lots of good docs)

[ricardoV94]

Add a "Sharp bits" section like JAX does, that explains where behavior deviates from python/numpy most obviously

https://jax.readthedocs.io/en/latest/notebooks/Common_Gotchas_in_JAX.html

• lazy compilation/evaluation
• if/else
• loops
• eq/neq
• set/inc_subtensor
• RandomVariables/updates
• Broadcasting
  ...?

[avm19]

Hi, I am currently reading PyTensor tutorials with the aim of improving my PyMC code performance. Here are my 2 cents.

1. "Big Picture overview" (currently missing or is too fragmented).
   There are so many submodules and classes, it is difficult to understand their role. It would be great to have an overview of all major classes and modules, how they interact with each other and their role in the lifecycle of a typical PyTensor application. The closest things to what I have in mind are Glossary, Extending - Graph Structure, Extending - Graph Rewriting, Extending - Ops, Extending - Overview of the compilation pipeline. Take chapters from "Extending PyTensor" User Guide that have little to do with the actual extending, unite them by a single narrative, and remove unnecessary details (such as API call signatures and specific code examples).

2. Docs are outdated.
   Some pages refer to classes and functions that don't exist any more. This is very confusing and raises entry barrier to users who haven't been around since the beginning of Theano. Simply going through the docs and correcting what's no longer true would be of great help.

3. Balance between "how to use" and "how it works".
   I feel like the docs in their current form err on the side of the first. For example, some tutorials are written like recipes: "... if you want to take a gradient, use this function that takes such and such arguments...". Sometimes it is better to explain how PyTensor works in terms of high-level abstractions (Variables, Ops, graph traversal, re-writing, compilation, what is stored, what is computed and when, in most general terms). Once the user understands the approach and general architecture of PyTensor, they would have no problem figuring out that there is must be a function that takes certain arguments and returns a certain type.

[ricardoV94]

Thanks that is great feedback. For context may I ask how did you find PyTensor/ this issue.

[avm19]

@ricardoV94 I hope I understand your question correctly. I was looking for Bayesian modelling in Python, found PyMC, hence PyTensor. I often check GitHub for open source libraries I use. I think I was looking not to provide a feedback, but for information, as Issues, PRs and Discussions sometimes contain insightful conversations. But this particular thread was on the surface, so I decided to comment.

[williambdean]

Tutorials meaning these docs?

[avm19]

Tutorials meaning these docs?

Yes.

[williambdean]

The Tutorial are pretty rich here but then the Examples are pretty sparse: https://pytensor.readthedocs.io/en/latest/gallery/gallery.html . Would it make sense to combine these? Feel like I don't know where to look when looking at the docs.

[ricardoV94]

More examples should probably be renamed to something else and More examples should be come a link to the PyTensor gallery.

The PyTensor gallery is more recent and to get things started we didn't bother too much synchronizing with the docs