Various documentation fixes (#2)

* Various docs fixes
* Fix import issue
* Add pylegendtestdata to docs requirements (for notebooks)
* Install pandoc on GitHub action runners
* Remove problematic "language" setting in Sphinx conf
* Update docstrings

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.github/workflows/main.yml

@@ -39,7 +39,6 @@ jobs:
 
   test-coverage:
     name: Calculate and upload test coverage
-    needs: build-and-test
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
@@ -59,7 +58,6 @@ jobs:
 
   build-docs:
     name: Build documentation
-    needs: build-and-test
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
@@ -70,8 +68,9 @@ jobs:
           python-version: '3.10'
       - name: Setup build environment
         run: |
+          sudo apt-get install -y pandoc
           python -m pip install --upgrade pip wheel setuptools
-          python -m pip install --upgrade .[docs]
+          python -m pip install --upgrade .[all]
       - name: Build docs for current ref
         run: |
           cd docs

.gitignore

@@ -4,6 +4,7 @@
 __pycache__/
 *.py[cod]
 *$py.class
+*.lh5
 
 # C extensions
 *.so

.pre-commit-config.yaml

@@ -37,12 +37,12 @@ repos:
   rev: "v3.3.1"
   hooks:
   - id: pyupgrade
-    args: ["--py36-plus"]
+    args: ["--py38-plus"]
 
 - repo: https://github.com/psf/black
   rev: "23.3.0"
   hooks:
-  - id: black
+  - id: black-jupyter
 
 - repo: https://github.com/pre-commit/mirrors-mypy
   rev: "v1.1.1"
@@ -62,18 +62,18 @@ repos:
   hooks:
   - id: flake8
     additional_dependencies: [
-      flake8-bugbear,
+      flake8-bugbear>=23.1.17,
       flake8-print,
-      flake8-docstrings,
+      # flake8-docstrings,
       pep8-naming
     ]
-    args: ["--docstring-convention", "numpy"]  # or google, change me
+    # args: ["--docstring-convention", "numpy"]  # or google, change me
 
 - repo: https://github.com/kynan/nbstripout
   rev: "0.6.1"
   hooks:
     - id: nbstripout
-      args: ["--strip-empty-cells",
+      args: ["--drop-empty-cells",
              "--extra-keys", "metadata.kernelspec metadata.language_info"]
 
 - repo: https://github.com/mgedmin/check-manifest

README.md

@@ -1,5 +1,6 @@
 # legend-pydataobj
 
+[![PyPI](https://img.shields.io/pypi/v/legend-pydataobj?logo=pypi)](https://pypi.org/project/legend-pydataobj/)
 ![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/legend-exp/legend-pydataobj?logo=git)
 [![GitHub Workflow Status](https://img.shields.io/github/checks-status/legend-exp/legend-pydataobj/main?label=main%20branch&logo=github)](https://github.com/legend-exp/legend-pydataobj/actions)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)

docs/source/conf.py

@@ -8,7 +8,7 @@
 sys.path.insert(0, Path(__file__).parents[2].resolve().as_posix())
 sys.path.append(Path("extensions").resolve().as_posix())
 
-project = "lgdo"
+project = "legend-pydataobj"
 copyright = "2023, the LEGEND Collaboration"
 version = get_distribution("legend-pydataobj").version
 
@@ -30,7 +30,6 @@
     ".md": "markdown",
 }
 master_doc = "index"
-language = "python"
 
 # Furo theme
 html_theme = "furo"
@@ -71,8 +70,8 @@
 ----
 
 This page has been automatically generated by nbsphinx_ and can be run as a
-Jupyter_ notebook available in the `pygama repository
-<https://github.com/legend-exp/pygama/tree/main/docs/source/notebooks>`_.
+Jupyter_ notebook available in the `legend-pydataobj repository
+<https://github.com/legend-exp/legend-pydataobj/tree/main/docs/source/notebooks>`_.
 
 .. _nbsphinx: https://nbsphinx.readthedocs.io/
 .. _Jupyter: https://jupyter.org/

docs/source/index.rst

@@ -1,10 +1,43 @@
-Welcome to lgdo's documentation!
-==========================================
+LEGEND Data Objects
+===================
 
-Table of Contents
------------------
+|legend-pydataobj| is a Python implementation of the `LEGEND Data Format Specification <1_>`_.
+
+Getting started
+---------------
+
+|legend-pydataobj| is published on the `Python Package Index <2_>`_. Install on
+local systems with `pip <3_>`_:
+
+.. tab:: Stable release
+
+    .. code-block:: console
+
+        $ pip install legend-pydataobj
+
+.. tab:: Unstable (``main`` branch)
+
+    .. code-block:: console
+
+        $ pip install legend-pydataobj@git+https://github.com/legend-exp/legend-pydataobj@main
+
+.. tab:: Linux Containers
+
+    Get a LEGEND container with |legend-pydataobj| pre-installed on `Docker hub
+    <https://hub.docker.com/r/legendexp/legend-software>`_ or follow
+    instructions on the `LEGEND wiki
+    <https://legend-exp.atlassian.net/l/cp/nF1ww5KH>`_.
+
+Next steps
+----------
 
 .. toctree::
    :maxdepth: 1
 
+   tutorials
    Package API reference <api/modules>
+
+.. _1: https://legend-exp.github.io/legend-data-format-specs
+.. _2: https://pypi.org/project/legend-pydataobj
+.. _3: https://pip.pypa.io/en/stable/getting-started
+.. |legend-pydataobj| replace:: *legend-pydataobj*