Open Saransh-cpp opened 2 years ago
@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?
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?
Can I work on this issue?
I think that would be very helpful. Thank you! @Saransh-cpp, could you help @Akhil-Sharma30 get started?
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).
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 -
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.)
Vector
usesblacken-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 -The hook - https://github.com/scikit-hep/vector/blob/d4ad49ecf1761e3a6561498d2405b7789d53deff/.pre-commit-config.yaml#L75-L80
These code blocks should ideally be parsable, and the
-E
option should be removed