Make code blocks in src/vector/_compute/*.py parsable

[Saransh-cpp]

Vector uses blacken-docs to prettify and format the docs. However, we use the -E flag to ignore any errors present in the code blocks.

Removing the -E option outputs the following errors -

blacken-docs.............................................................Failed
- hook id: blacken-docs
- exit code: 1

src/vector/_compute/lorentz/gamma.py:7: code block parse error Cannot parse: 2:0: Lorentz.gamma(self)
src/vector/_compute/lorentz/beta.py:7: code block parse error Cannot parse: 2:0: Lorentz.beta(self)
src/vector/_compute/lorentz/Et2.py:7: code block parse error Cannot parse: 2:0: Lorentz.Et2(self)
src/vector/_compute/spatial/eta.py:7: code block parse error Cannot parse: 2:0: Spatial.eta(self)
src/vector/_compute/planar/rho2.py:7: code block parse error Cannot parse: 2:0: Planar.rho2(self)
src/vector/_compute/planar/phi.py:7: code block parse error Cannot parse: 2:0: Planar.phi(self)
src/vector/_compute/spatial/cottheta.py:7: code block parse error Cannot parse: 2:0: Spatial.cottheta(self)
src/vector/_compute/lorentz/Mt.py:7: code block parse error Cannot parse: 2:0: Lorentz.Mt(self)
src/vector/_compute/lorentz/rapidity.py:7: code block parse error Cannot parse: 2:0: Lorentz.rapidity(self)
src/vector/_compute/spatial/z.py:7: code block parse error Cannot parse: 2:0: Spatial.z(self)
src/vector/_compute/lorentz/Et.py:7: code block parse error Cannot parse: 2:0: Lorentz.Et(self)
src/vector/_methods.py:497: code block parse error Cannot parse: 1:10: obj["xx"] obj["xy"]
src/vector/_methods.py:763: code block parse error Cannot parse: 1:10: obj["xx"] obj["xy"] obj["xz"]
src/vector/_methods.py:1080: code block parse error Cannot parse: 1:10: obj["xx"] obj["xy"] obj["xz"] obj["xt"]
src/vector/_compute/spatial/costheta.py:7: code block parse error Cannot parse: 2:0: Spatial.costheta(self)
src/vector/_compute/lorentz/boostX_gamma.py:7: code block parse error Cannot parse: 1:27: Lorentz.boostX(self, gamma=)
src/vector/_compute/planar/y.py:7: code block parse error Cannot parse: 2:0: Planar.y(self)
src/vector/_compute/spatial/mag2.py:7: code block parse error Cannot parse: 2:0: Spatial.mag2(self)
src/vector/_compute/planar/rho.py:7: code block parse error Cannot parse: 2:0: Planar.rho(self)
src/vector/_compute/lorentz/Mt2.py:7: code block parse error Cannot parse: 2:0: Lorentz.Mt2(self)
src/vector/_compute/lorentz/t2.py:7: code block parse error Cannot parse: 2:0: Lorentz.t2(self)
src/vector/_compute/lorentz/t.py:7: code block parse error Cannot parse: 2:0: Lorentz.t(self)
src/vector/_compute/lorentz/tau.py:7: code block parse error Cannot parse: 2:0: Lorentz.tau(self)
src/vector/_compute/lorentz/tau2.py:7: code block parse error Cannot parse: 2:0: Lorentz.tau2(self)
src/vector/_compute/spatial/mag.py:7: code block parse error Cannot parse: 2:0: Spatial.mag(self)
src/vector/_compute/spatial/theta.py:7: code block parse error Cannot parse: 2:0: Spatial.theta(self)
src/vector/_compute/planar/x.py:7: code block parse error Cannot parse: 2:0: Planar.x(self)

The hook -

vector/.pre-commit-config.yaml

Lines 75 to 80 in d4ad49e

	- repo: https://github.com/asottile/blacken-docs
	rev: v1.12.1
	hooks:
	- id: blacken-docs
	args: ["-E"]
	additional_dependencies: [black==22.3.0]

These code blocks should ideally be parsable, and the -E option should be removed

[matthewfeickert]

@Saransh-cpp were you thinking of things like simple examples to replace what Jim had added in PR #55?

--- a/src/vector/_compute/lorentz/tau2.py
+++ b/src/vector/_compute/lorentz/tau2.py
@@ -4,10 +4,11 @@
 # or https://github.com/scikit-hep/vector for details.
 
 """
-.. code-block:: python
+Example:
 
-    @property
-    Lorentz.tau2(self)
+    >>> import vector
+    >>> vector.obj(pt=3, phi=2, eta=1, mass=4).tau2
+    16.0
 """
 from __future__ import annotations

or something else that extends instead of replaces?

[Saransh-cpp]

My initial thought was to replace the current examples with copy-pastable examples. Now that I think of it, the current examples are also very informative for vector's developers and users. Maybe we can do something like -

.. code-block:: python
 
    @property
    Lorentz.tau2(self)

+Example:
+
+.. code-block:: python
+
+    >>> import vector
+    >>> vector.obj(pt=3, phi=2, eta=1, mass=4).tau2
+    16.0

and let blacken-docs fail on the Lorentz.tau2(self) code block?

[Akhil-Sharma30]

Can I work on this issue?

[jpivarski]

I think that would be very helpful. Thank you! @Saransh-cpp, could you help @Akhil-Sharma30 get started?

[henryiii]

and let blacken-docs fail on the Lorentz.tau2(self) code block?

You don't need to "let it fail", just use pycon for the block language. Blacken-docs won't pick it up then (same with ipython and pytb), and the syntax highlighter might even do a better job (it does on GitHub, I know).

Or you can avoid the >>>, I'm not wildly fond of adding characters that can't be copy-pasted for copy-paste examples. (Unless the code renderer can make those parts not copy-passable, sometimes they can).

[Saransh-cpp]

I think that would be very helpful. Thank you! @Saransh-cpp, could you help @Akhil-Sharma30 get started?

Yes, definitely! Sorry, I wasn't able to comment before.

@Akhil-Sharma30 can you start with @henryiii's suggestion and open a new PR for changing some of the code blocks to pycon? I think we can keep the code blocks as it is, given that they are developer-facing (the sub-package name starts with _), and not user-facing. So for example, you'll have to update -

vector/src/vector/_compute/lorentz/Et2.py

Line 7 in 9a67b1f

.. code-block:: python

with pycon in the place of python. Similarly for all the other failing code blocks (you can remove "-E" from blacken-docs' config in .pre-commit-config.yaml to obtain all the errors locally.)