update docs with example notebook (#37)

scikit-hep · Sep 1, 2022 · 14e6600 · 14e6600
1 parent 5c1323d
commit 14e6600
Show file tree

Hide file tree

Showing 16 changed files with 1,965 additions and 116 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -1,4 +1,4 @@
-name: docs
+name: Docs
 
 on:
   pull_request:
@@ -21,7 +21,9 @@ jobs:
     - uses: actions/setup-python@v2
       with:
         python-version: "3.9"
-    - run: python -m pip install -v -e .[doc]
+    - run: sudo apt-get install pandoc
+    - run: python -m pip install --prefer-binary -v -e .[doc]
+    - run: python -m ipykernel install --user --name python3
     - run: python docs/build.py
     - uses: actions/upload-pages-artifact@v1
       with:

diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
+.DS_Store
 var
 build
 dist
@@ -20,5 +21,8 @@ src/pyhepmc/_version.py
 .vscode
 docs/xml
 docs/_build
-docs/about.rst.in
+docs/index.rst
 docs/generated_reference.rst.in
+examples/event.png
+examples/event.svg
+examples/modified_event.dat
diff --git a/docs/build.py b/docs/build.py
@@ -7,8 +7,8 @@
 sys.path.append(cdir)
 os.chdir(cdir)
 
-import generate_about  # noqa
+import generate_index  # noqa
 
-cmd = "sphinx-build -W -b html -d _build/doctrees . _build/html"
+cmd = "sphinx-build -W -a -E -b html -d _build/doctrees . _build/html"
 
 sys.exit(subp.call(cmd.split()))
diff --git a/docs/conf.py b/docs/conf.py
@@ -18,9 +18,8 @@
 
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.coverage",
-    "sphinx.ext.githubpages",
     "sphinx.ext.napoleon",
+    "nbsphinx",
 ]
 
 # templates_path = ["_templates"]

diff --git a/docs/examples.rst b/docs/examples.rst
@@ -0,0 +1,7 @@
+Examples
+========
+
+.. toctree::
+    :maxdepth: 1
+
+    examples/basics
diff --git a/docs/examples/basics.ipynb b/docs/examples/basics.ipynb
diff --git a/docs/examples/event.png b/docs/examples/event.png
diff --git a/docs/examples/event.svg b/docs/examples/event.svg
diff --git a/docs/examples/modified_event.dat b/docs/examples/modified_event.dat
@@ -0,0 +1,57 @@
+HepMC::Version 3.02.05
+HepMC::Asciiv3-START_EVENT_LISTING
+T Pythia\|6.4.28\|Legacy Pythia 6 event
+E 0 19 40
+U GEV MM
+A -19 sparkly 1
+A -17 sparkly 1
+A -15 sparkly 1
+A -13 sparkly 1
+A -12 sparkly 1
+P 1 0 2212 0.000e+00 0.000e+00 4.999e+01 5.000e+01 9.383e-01 3
+P 2 0 2212 0.000e+00 0.000e+00 -4.999e+01 5.000e+01 9.383e-01 3
+P 3 1 1 -2.181e-02 5.881e-01 -4.847e-01 7.624e-01 -0.000e+00 3
+P 4 2 1 -2.140e+00 6.307e-01 -5.560e+00 5.991e+00 -0.000e+00 3
+P 5 3 1 -2.181e-02 5.881e-01 -4.847e-01 7.624e-01 0.000e+00 3
+P 6 4 1 -2.140e+00 6.307e-01 -5.560e+00 5.991e+00 0.000e+00 3
+V -5 0 [5,6]
+P 7 -5 1 -2.243e+00 8.092e-01 -5.434e+00 5.943e+00 3.300e-01 3
+P 8 -5 1 8.114e-02 4.095e-01 -6.109e-01 8.102e-01 3.300e-01 3
+P 9 7 1 -2.243e+00 8.092e-01 -5.434e+00 5.943e+00 3.300e-01 2
+P 10 1 2203 2.181e-02 -5.881e-01 4.961e+01 4.962e+01 7.713e-01 2
+P 11 8 1 8.114e-02 4.095e-01 -6.109e-01 8.102e-01 3.300e-01 2
+P 12 2 2203 2.140e+00 -6.307e-01 -4.356e+01 4.363e+01 7.713e-01 2
+V -8 0 [9,10]
+P 13 -8 92 -2.221e+00 2.212e-01 4.418e+01 5.556e+01 3.363e+01 2
+P 14 13 331 -1.174e+00 8.077e-01 -3.080e+00 3.526e+00 9.582e-01 2
+P 15 13 111 -3.152e-01 -3.598e-02 2.990e-01 4.564e-01 1.350e-01 2
+P 16 13 -211 -7.064e-01 3.103e-02 -2.166e+00 2.283e+00 1.396e-01 1
+P 17 13 211 -4.561e-01 -4.751e-01 8.121e+00 8.149e+00 1.396e-01 1
+P 18 13 2112 9.004e-01 -2.513e-01 6.083e+00 6.226e+00 9.396e-01 1
+P 19 13 211 -4.700e-01 1.449e-01 3.492e+01 3.492e+01 1.396e-01 1
+V -9 0 [11,12]
+P 20 -9 92 2.221e+00 -2.212e-01 -4.418e+01 4.444e+01 4.282e+00 2
+P 21 20 113 5.997e-01 3.451e-01 -3.381e+00 3.512e+00 6.540e-01 2
+P 22 20 221 1.084e-01 -4.203e-01 -1.233e+01 1.235e+01 5.474e-01 2
+P 23 20 2214 1.279e+00 4.004e-01 -2.004e+01 2.013e+01 1.347e+00 2
+P 24 20 111 2.340e-01 -5.463e-01 -8.419e+00 8.441e+00 1.350e-01 2
+P 25 14 22 -3.787e-01 1.380e-01 -5.727e-01 7.003e-01 0.000e+00 1
+P 26 14 113 -7.951e-01 6.696e-01 -2.507e+00 2.826e+00 7.868e-01 2
+V -12 0 [15] @ -4.174e-06 -4.765e-07 3.960e-06 6.044e-06
+P 27 -12 22 -6.540e-02 -4.092e-02 1.411e-01 1.608e-01 0.000e+00 1
+P 28 -12 22 -2.498e-01 4.942e-03 1.579e-01 2.956e-01 0.000e+00 1
+P 29 21 211 -9.967e-02 6.182e-02 -5.559e-01 5.850e-01 1.396e-01 1
+P 30 21 -211 6.993e-01 2.833e-01 -2.825e+00 2.927e+00 1.396e-01 1
+P 31 22 22 -7.565e-02 -4.856e-01 -7.709e+00 7.725e+00 0.000e+00 1
+P 32 22 22 1.840e-01 6.534e-02 -4.622e+00 4.626e+00 0.000e+00 1
+P 33 23 2212 1.315e+00 5.050e-01 -1.675e+01 1.684e+01 9.383e-01 1
+P 34 23 111 -3.566e-02 -1.047e-01 -3.292e+00 3.296e+00 1.350e-01 2
+V -17 0 [24] @ 3.911e-05 -9.133e-05 -1.407e-03 1.411e-03
+P 35 -17 22 1.023e-01 -3.972e-01 -5.805e+00 5.820e+00 0.000e+00 1
+P 36 -17 22 1.317e-01 -1.492e-01 -2.614e+00 2.621e+00 0.000e+00 1
+P 37 26 -211 -4.627e-01 -5.907e-02 -8.370e-01 9.683e-01 1.396e-01 1
+P 38 26 211 -3.324e-01 7.287e-01 -1.670e+00 1.858e+00 1.396e-01 1
+V -19 0 [34] @ -1.194e-06 -3.506e-06 -1.102e-04 1.104e-04
+P 39 -19 22 -7.436e-02 -1.377e-02 -1.472e+00 1.474e+00 0.000e+00 1
+P 40 -19 22 3.870e-02 -9.092e-02 -1.820e+00 1.822e+00 0.000e+00 1
+HepMC::Asciiv3-END_EVENT_LISTING
diff --git a/docs/generate_about.py b/docs/generate_about.py
diff --git a/docs/generate_index.py b/docs/generate_index.py
@@ -0,0 +1,12 @@
+# Generate about.rst from README.rst: must change paths to images
+with open("../README.rst") as f:
+    content = f.read()
+
+content1 = content.replace("image:: docs/", "image:: ./")
+
+with open("index.rst.in") as f:
+    content2 = f.read()
+
+with open("index.rst", "w") as f:
+    f.write(content1 + "\n\n")
+    f.write(content2)
diff --git a/docs/index.rst → docs/index.rst.in b/docs/index.rst → docs/index.rst.in
@@ -1,7 +1,6 @@
-.. include:: about.rst.in
-
 .. toctree::
     :hidden:
 
     reference
+    examples
     citation
diff --git a/docs/reference.rst b/docs/reference.rst
@@ -14,3 +14,10 @@ pyhepmc.io
 .. automodule:: pyhepmc.io
   :members:
   :undoc-members:
+
+pyhepmc.view
+------------
+
+.. automodule:: pyhepmc.view
+  :members:
+  :undoc-members:
diff --git a/examples/visualization.ipynb b/examples/visualization.ipynb
diff --git a/setup.cfg b/setup.cfg
@@ -35,6 +35,9 @@ test =
 doc =
     sphinx
     sphinx-rtd-theme
+    nbsphinx
+    ipython
+    ipykernel
 
 [flake8]
 max-line-length = 90

diff --git a/src/pyhepmc/_autodoc.py b/src/pyhepmc/_autodoc.py
@@ -253,8 +253,7 @@
 Constructor based on particle data.""",
     "GenParticle.add_attribute": """Add an attribute to this particle.
 
-This will overwrite existing attribute if an attribute with the same name is present. The attribute will be stored in the parent_event().
-            false if there is no parent_event();.""",
+This will overwrite existing attribute if an attribute with the same name is present. The attribute will be stored in the parent_event(). false if there is no parent_event();.""",
     "GenParticle.attribute": """Get attribute of type T.""",
     "GenParticle.attribute_as_string": """Get attribute of any type as string.""",
     "GenParticle.attribute_names": """Get list of names of attributes assigned to this particle.""",
@@ -378,7 +377,6 @@
 ----------
 evt:
     Event to be filled.""",
-    "ReaderAscii.run_info": """Get the global GenRunInfo object.""",
     "ReaderAscii.skip": """skip events.""",
     "ReaderAsciiHepMC2": """Parser for HepMC2 I/O files.""",
     "ReaderAsciiHepMC2.__init__": """Default constructor.
@@ -390,7 +388,6 @@
     "ReaderAsciiHepMC2.failed": """Return status of the stream.""",
     "ReaderAsciiHepMC2.options": """Access options.""",
     "ReaderAsciiHepMC2.read_event": """Implementation of Reader::read_event.""",
-    "ReaderAsciiHepMC2.run_info": """Get the global GenRunInfo object.""",
     "ReaderAsciiHepMC2.skip": """skip events.""",
     "ReaderGZ": """GenEvent I/O parsing for compressed files.""",
     "ReaderGZ.__init__": """Constructor.
@@ -405,7 +402,6 @@
 ----------
 evt:
     Event to be filled.""",
-    "ReaderGZ.run_info": """Get the global GenRunInfo object.""",
     "ReaderGZ.skip": """skip events.""",
     "ReaderHEPEVT": """GenEvent I/O parsing and serialization for HEPEVT files.""",
     "ReaderHEPEVT.__init__": """Default constructor.
@@ -425,7 +421,6 @@
 ----------
 i:
     Particle id.""",
-    "ReaderHEPEVT.run_info": """Get the global GenRunInfo object.""",
     "ReaderHEPEVT.skip": """skip events.""",
     "ReaderLHEF": """GenEvent I/O parsing and serialization for LHEF files.""",
     "ReaderLHEF.__init__": """The ctor to read from stream.
@@ -437,14 +432,12 @@
     "ReaderLHEF.failed": """State.""",
     "ReaderLHEF.options": """Access options.""",
     "ReaderLHEF.read_event": """Reading event.""",
-    "ReaderLHEF.run_info": """Get the global GenRunInfo object.""",
     "ReaderLHEF.skip": """skip events.""",
     "ReaderMT": """Multithreader GenEvent I/O parsing.""",
     "ReaderMT.close": """Close file and/or stream.""",
     "ReaderMT.failed": """Get file and/or stream error state.""",
     "ReaderMT.options": """Access options.""",
     "ReaderMT.read_event": """Fill next event from input into evt.""",
-    "ReaderMT.run_info": """Get the global GenRunInfo object.""",
     "ReaderMT.skip": """skip or fast forward reading of some events.""",
     "Setup": """Configuration for HepMC.