Merge pull request #257 from gipert/packaging

Switch to declarative package management

.github/pull_request_template.md

@@ -0,0 +1,8 @@
+Before submitting a pull request, please make sure you've read and understood
+[pygama's contribution
+guide](https://legend-exp.github.io/pygama/main/contributing.html). In
+particular, do not forget to:
+
+* Update existing or add new **tests**
+* Update existing or add new **documentation**
+* Address any issue reported by GitHub bots

.github/workflows/main.yml

@@ -28,28 +28,12 @@ jobs:
         python-version: ${{ matrix.python-version }}
     - name: Get dependencies and install the package
       run: |
-        .github/workflows/get-dependencies.sh
-        python -m pip install .
+        python -m pip install --upgrade pip wheel setuptools
+        python -m pip install --upgrade .[test]
     - name: Run unit tests
       run: |
         pytest
 
-  # test-in-legend-container:
-  #   name: Test pygama in LEGEND container
-  #   runs-on: ubuntu-latest
-  #   container: docker://legendexp/legend-base:${{ matrix.docker-tag }}
-  #   strategy:
-  #     fail-fast: false
-  #     matrix:
-  #       docker-tag: [latest, ubuntu]
-
-  #   steps:
-  #   - uses: actions/checkout@v2
-  #   - name: Install and run unit tests
-  #     run: |
-  #       python -m pip install .
-  #       pytest
-
   test-coverage:
     name: Calculate and upload test coverage
     needs: build-and-test
@@ -64,28 +48,27 @@ jobs:
 
       - name: Generate Report
         run: |
-          .github/workflows/get-dependencies.sh
-          python -m pip install .
-          python -m pip install coverage
+          python -m pip install --upgrade pip wheel setuptools
+          python -m pip install --upgrade .[test]
           coverage run -m pytest
       - name: Upload Coverage to codecov.io
         uses: codecov/codecov-action@v2
 
   deploy-docs:
-    name: Deploy documentation on legend-exp.github.io/pygama
+    name: Build documentation
     needs: build-and-test
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
       - uses: actions/setup-python@v2
         with:
-          python-version: 3.8
+          python-version: '3.8'
       - name: Setup build environment
         run: |
-          git fetch --prune --no-recurse-submodules --depth=1 origin
-          .github/workflows/get-dependencies.sh
-          pip install sphinx sphinx-rtd-theme myst-parser
-          pip install git+https://github.com/samtygier-stfc/sphinx-multiversion.git@prebuild_command
+          python -m pip install --upgrade pip wheel setuptools
+          python -m pip install --upgrade .[docs]
       - name: Build docs for current ref
         run: |
           cd docs

.gitignore

@@ -10,9 +10,7 @@
 *~
 *.csv
 
-pygama/git.py
-experiments/lpgta/cori_slurm/logs/
-experiments/oppi/logs
+/src/pygama/_version.py
 
 # -------------------- github-generated stuff -------------------
 # Byte-compiled / optimized / DLL files

docs/Makefile

@@ -19,7 +19,7 @@ allver-info:
 	sphinx-multiversion --dump-metadata "$(SOURCEDIR)" "$(BUILDDIRALL)"
 
 apidoc: clean-apidoc
-	sphinx-apidoc --private --module-first --force --output-dir "$(SOURCEDIR)/generated" ../pygama $(PY_SOURCE_EXCLUDE)
+	sphinx-apidoc --private --module-first --force --output-dir "$(SOURCEDIR)/generated" ../src/pygama $(PY_SOURCE_EXCLUDE)
 
 clean-apidoc:
 	rm -rf "$(SOURCEDIR)/generated"

docs/source/.py_api_exclude

@@ -1 +1 @@
-../pygama/version.py
+../src/pygama/_version.py

docs/source/conf.py

@@ -1,9 +1,9 @@
 # Configuration file for the Sphinx documentation builder.
 
-import pathlib
 import sys
+from pathlib import Path
 
-sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
+sys.path.insert(0, Path('../../src').resolve().as_posix())
 
 project = 'pygama'
 copyright = '2020, the LEGEND Collaboration'
@@ -38,10 +38,10 @@
 # could be unmet at build time
 autodoc_mock_imports = [
     'pandas',
-    'numpy',
+    # 'numpy',
     'matplotlib',
     'mplhep',
-    'scimath',
+    'scipy',
     'numba',
     'pytest',
     'pyhf',
@@ -67,11 +67,11 @@
 # intersphinx
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
-    'numpy': ('http://docs.scipy.org/doc/numpy', None),
+    'numpy': ('https://numpy.org/doc/stable', None),
     'numba': ('https://numba.readthedocs.io/en/stable', None),
-    'scipy': ('http://docs.scipy.org/doc/scipy/reference', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy', None),
     'pandas': ('https://pandas.pydata.org/docs', None),
-    'matplotlib': ('http://matplotlib.org/stable', None),
+    'matplotlib': ('https://matplotlib.org/stable', None),
     'iminuit': ('https://iminuit.readthedocs.io/en/stable', None)
 }
 

docs/source/contributing.rst

@@ -5,6 +5,13 @@ The following rules and conventions have been established for the package
 development and are enforced throughout the entire code base. Merge requests
 that do not comply to the following directives will be rejected.
 
+All extra tools needed to develop *pygama* are listed as optional dependencies
+and can be installed via pip by running:
+
+.. code-block:: console
+
+    $ pip install .[all]
+
 Code style
 ----------
 
@@ -56,19 +63,25 @@ Testing
 * Unit tests are automatically run for every push event and pull request to the
   remote Git repository on a remote server (currently handled by GitHub
   actions). Every pull request must pass all tests before being approved for
-  merging.
+  merging. Running the test suite is simple:
+
+  .. code-block:: console
+
+     $ pip install .[test]
+     $ pytest
+
 * Additionally, pull request authors are required to provide tests with
   sufficient code coverage for every proposed change or addition. If necessary,
   high-level functional tests should be updated. We currently rely on
   `codecov.io <https://app.codecov.io/gh/legend-exp/pygama>`_ to keep track of
   the test coverage. To generate a local coverage report (recommended before
-  submitting pull requests), the ``coverage`` Python package is needed:
+  submitting pull requests), run:
 
   .. code-block:: console
 
-    $ pip install coverage
-    $ coverage run -m pytest
-    $ coverage report
+     $ pip install .[test]
+     $ coverage run -m pytest
+     $ coverage report
 
 Documentation
 -------------
@@ -121,24 +134,20 @@ Building documentation
 ^^^^^^^^^^^^^^^^^^^^^^
 
 Scripts and tools to build documentation are located below ``docs/``. To build
-documentation, the ``sphinx``, ``sphinx-rtd-theme`` and ``sphinx-multiversion``
-Python packages are required. At the moment, *pygama* is using a ``sphinx-multiversion``
-functionality only available through a fork of the project
-(``samtygier-stfc/sphinx-multiversion``, at the ``prebuild_command`` branch). With pip,
-it can be installed with the following command:
+documentation, ``sphinx``, ``sphinx-rtd-theme`` and a couple of additional
+Python packages are required. You can get all the needed dependencies by running:
 
 .. code-block:: console
 
-    $ pip install git+https://github.com/samtygier-stfc/sphinx-multiversion.git@prebuild_command
+   $ pip install .[docs]
 
-This will probably change in the future. To build documentation for the current
-Git ref, run the following commands:
+To build documentation for the current Git ref, run the following commands:
 
 .. code-block:: console
 
-    $ cd docs
-    $ make clean
-    $ make
+   $ cd docs
+   $ make clean
+   $ make
 
 Documentation can be then displayed by opening ``build/html/index.html`` with a
 web browser.  To build documentation for all main *pygama* versions (development
@@ -162,22 +171,18 @@ new project version must implement the following procedures:
 
 * `Semantic versioning <https://semver.org>`_ is adopted. The version string
   uses the ``MAJOR.MINOR.PATCH`` format.
-* The version string is manually specified in ``pygama/version.py``. If needed
-  elsewhere in the source code (e.g. in ``setup.py``), must be read in from here.
 * To release a new **minor** or **major version**, the following procedure
   should be followed:
 
-  1. The *pygama* version is updated in ``pygama/version.py``
-  2. A new branch with name ``releases/vMAJOR.MINOR`` (note the ``v``) containing
+  1. A new branch with name ``releases/vMAJOR.MINOR`` (note the ``v``) containing
      the code at the intended stage is created
-  3. The commit is tagged with a descriptive message: ``git tag vMAJOR.MINOR.0
+  2. The commit is tagged with a descriptive message: ``git tag vMAJOR.MINOR.0
      -m 'short descriptive message here'`` (note the ``v``)
-  4. Changes are pushed to the remote: ``git push --tags origin releases/vMAJOR.MINOR``
+  3. Changes are pushed to the remote: ``git push --tags origin releases/vMAJOR.MINOR``
 
 * To release a new **patch version**, the following procedure should be followed:
 
-  1. The *pygama* version is updated in ``pygama/version.py``
-  2. A commit with the patch is created on the relevant release branch
+  1. A commit with the patch is created on the relevant release branch
      ``releases/vMAJOR.MINOR``
-  3. The commit is tagged: ``git tag vMAJOR.MINOR.PATCH`` (note the ``v``)
-  4. Changes are pushed to the remote: ``git push --tags origin releases/vMAJOR.MINOR``
+  2. The commit is tagged: ``git tag vMAJOR.MINOR.PATCH`` (note the ``v``)
+  3. Changes are pushed to the remote: ``git push --tags origin releases/vMAJOR.MINOR``

docs/source/install.rst

@@ -6,18 +6,25 @@ Install on local systems with:
 .. code-block:: console
 
     $ git clone https://github.com/legend-exp/pygama
-    $ pip install -e pygama
+    $ pip install pygama
 
-You can omit the ``-e`` flag (editable mode) if you do not plan to develop
-pygama. If you do not have admin rights you can install pygama as a normal
-user:
+Append the ``-e`` flag (editable mode) if you plan to develop *pygama*. If you
+do not have admin rights you can install pygama as a normal user:
 
 .. code-block:: console
 
-    $ pip install -e pygama --user
+    $ pip install pygama --user
 
 and make sure that your ``PYTHONPATH`` environment variable is aware of the
-install location. To uninstall pygama run:
+install location. Optionally-required dependencies can be also collected:
+
+.. code-block:: console
+
+    $ pip install pygama[daq]  # if you need to convert DAQ files to LH5
+    $ pip install pygama[test] # if you want to run package test files
+    $ pip install pygama[docs] # if you need to build documentation
+
+To uninstall pygama run:
 
 .. code-block:: console
 

pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = [
+    "setuptools>=42.0.0",
+    "setuptools_scm[toml]>=3.4",
+]
+
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+write_to = "src/pygama/_version.py"
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = ["-ra", "--showlocals", "--strict-markers", "--strict-config"]
+xfail_strict = true
+filterwarnings = "error"
+log_cli_level = "info"
+testpaths = "tests"
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3