From bd704cd2a389304460c05499feabc33d1ec98e5b Mon Sep 17 00:00:00 2001 From: Luigi Pertoldi Date: Wed, 28 Feb 2024 11:13:30 +0100 Subject: [PATCH] Update citation-related docs --- CITATION.cff | 6 +- README.md | 4 + docs/source/developer.rst | 242 ++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 18 +++ 4 files changed, 267 insertions(+), 3 deletions(-) create mode 100644 docs/source/developer.rst diff --git a/CITATION.cff b/CITATION.cff index 65206e6..bb00829 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -1,7 +1,7 @@ cff-version: 1.2.0 -title: dspeed -doi: FILLME -date-released: 2024-01-01 +title: legend-daq2lh5 +doi: https://doi.org/10.5281/zenodo.10721223 +date-released: 2024-02-28 url: https://github.com/github-linguist/linguist message: "If you use this software, please cite it as below." authors: diff --git a/README.md b/README.md index 33eb4dd..49beded 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ ![GitHub pull requests](https://img.shields.io/github/issues-pr/legend-exp/legend-daq2lh5?logo=github) ![License](https://img.shields.io/github/license/legend-exp/legend-daq2lh5) [![Read the Docs](https://img.shields.io/readthedocs/legend-daq2lh5?logo=readthedocs)](https://legend-daq2lh5.readthedocs.io) +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10721223.svg)](https://doi.org/10.5281/zenodo.10721223) JSON-configurable conversion of digitized data into [LEGEND HDF5](https://legend-exp.github.io/legend-data-format-specs/dev/hdf5/), @@ -23,3 +24,6 @@ Currently supported DAQ data formats: - FlashCam - [Struck SIS3302](https://www.struck.de/sis3302.htm) - [Struck SIS3316](https://www.struck.de/sis3316.html) + +If you are using this software, consider +[citing](https://doi.org/10.5281/zenodo.10721223)! diff --git a/docs/source/developer.rst b/docs/source/developer.rst new file mode 100644 index 0000000..a76d372 --- /dev/null +++ b/docs/source/developer.rst @@ -0,0 +1,242 @@ +Developer's guide +================= + +.. note:: + + The https://learn.scientific-python.org webpages are an extremely valuable + learning resource for Python software developer. The reader is referred to + that for any detail not covered in the following guide. + +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. + +To start developing *legend-daq2lh5*, fork the remote repository to your personal +GitHub account (see `About Forks +`_). +If you have not set up your ssh keys on the computer you will be working on, +please follow `GitHub's instructions +`_. +Once you have your own fork, you can clone it via +(replace "yourusername" with your GitHub username): + +.. code-block:: console + + $ git clone git@github.com:yourusername/legend-daq2lh5.git + +All extra tools needed to develop *legend-daq2lh5* are listed as optional +dependencies and can be installed via pip by running: + +.. code-block:: console + + $ cd legend-daq2lh5 + $ pip install -e '.[all]' # single quotes are not needed on bash + +.. important:: + + Pip's ``--editable | -e`` flag let's you install the package in "developer + mode", meaning that any change to the source code will be directly + propagated to the installed package and importable in scripts. + +.. tip:: + + It is strongly recommended to work inside a virtual environment, which + guarantees reproductibility and isolation. For more details, see + `learn.scientific-python.org + `_. + +Code style +---------- + +* All functions and methods (arguments and return types) must be + `type-annotated `_. Type + annotations for variables like class attributes are also highly appreciated. +* Messaging to the user is managed through the :mod:`logging` module. Do not + add :func:`print` statements. To make a logging object available in a module, + add this: + + .. code-block:: python + + import logging + + log = logging.getLogger(__name__) + + at the top. In general, try to keep the number of :func:`logging.debug` calls + low and use informative messages. :func:`logging.info` calls should be + reserved for messages from high-level routines and very sporadic. Good code + is never too verbose. +* If an error condition leading to undefined behavior occurs, raise an + exception. try to find the most suitable between the `built-in exceptions + `_, otherwise ``raise + RuntimeError("message")``. Do not raise ``Warning``\ s, use + :func:`logging.warning` for that and don't abort the execution. +* Warning messages (emitted when a problem is encountered that does not lead to + undefined behavior) must be emitted through :func:`logging.warning` calls. + +A set of `pre-commit `_ hooks is configured to make +sure that *legend-daq2lh5* coherently follows standard coding style conventions. +The pre-commit tool is able to identify common style problems and automatically +fix them, wherever possible. Configured hooks are listed in the +``.pre-commit-config.yaml`` file at the project root folder. They are run +remotely on the GitHub repository through the `pre-commit bot +`_, but should also be run locally before submitting a +pull request: + +.. code-block:: console + + $ cd legend-daq2lh5 + $ pip install '.[test]' + $ pre-commit run --all-files # analyse the source code and fix it wherever possible + $ pre-commit install # install a Git pre-commit hook (strongly recommended) + +For a more comprehensive guide, check out the `learn.scientific-python.org +documentation about code style +`_. + +Testing +------- + +* The *legend-daq2lh5* test suite is available below ``tests/``. We use `pytest + `_ to run tests and analyze their output. As + a starting point to learn how to write good tests, reading of `the + relevant learn.scientific-python.org webpage + `_ is + recommended. + +* 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. Running the test suite is simple: + + .. code-block:: console + + $ cd legend-daq2lh5 + $ 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 `_ to keep track of + test coverage. A local report, which must be inspected before submitting pull + requests, can be generated by running: + + .. code-block:: console + + $ pytest --cov=lgdo + +Documentation +------------- + +We adopt best practices in writing and maintaining *legend-daq2lh5*'s +documentation. When contributing to the project, make sure to implement the +following: + +* Documentation should be exclusively available on the Project website + `legend-daq2lh5.readthedocs.io `_. No READMEs, + GitHub/LEGEND wiki pages should be written. +* Pull request authors are required to provide sufficient documentation for + every proposed change or addition. +* Documentation for functions, classes, modules and packages should be provided + as `Docstrings `_ along with the respective + source code. Docstrings are automatically converted to HTML as part of the + *legend-daq2lh5* package API documentation. +* General guides, comprehensive tutorials or other high-level documentation + (e.g. referring to how separate parts of the code interact between each + other) must be provided as separate pages in ``docs/source/`` and linked in + the table of contents. +* Jupyter notebooks should be added to the main Git repository below + ``docs/source/notebooks``. +* Before submitting a pull request, contributors are required to build the + documentation locally and resolve and warnings or errors. + +Writing documentation +^^^^^^^^^^^^^^^^^^^^^ + +We adopt the following guidelines for writing documentation: + +* Documentation source files must formatted in reStructuredText (reST). A + reference format specification is available on the `Sphinx reST usage guide + `_. + Usage of `Cross-referencing syntax + `_ + in general and `for Python objects + `_ + in particular is recommended. We also support cross-referencing external + documentation via `sphinx.ext.intersphinx + `_, + when referring for example to :class:`pandas.DataFrame`. +* To document Python objects, we also adopt the `NumPy Docstring style + `_. Examples are + available `here + `_. +* We support also the Markdown format through the `MyST-Parser + `_. +* Jupyter notebooks placed below ``docs/source/notebooks`` are automatically + rendered to HTML pages by the `nbsphinx `_ + extension. + +Building documentation +^^^^^^^^^^^^^^^^^^^^^^ + +Scripts and tools to build documentation are located below ``docs/``. To build +documentation, ``sphinx`` and a couple of additional Python packages are +required. You can get all the needed dependencies by running: + +.. code-block:: console + + $ cd legend-daq2lh5 + $ pip install '.[docs]' + +`Pandoc `_ is also required to render +Jupyter notebooks. To build documentation, run the following commands: + +.. code-block:: console + + $ cd docs + $ make clean + $ make + +Documentation can be then displayed by opening ``build/html/index.html`` with a +web browser. Documentation for the :mod:`legend-daq2lh5` website is built and deployed by +`Read the Docs `_. + +Versioning +---------- + +Collaborators with push access to the GitHub repository that wish to release a +new project version must implement the following procedures: + +* `Semantic versioning `_ is adopted. The version string + uses the ``MAJOR.MINOR.PATCH`` format. +* To release a new **minor** or **major version**, the following procedure + should be followed: + + 1. A new branch with name ``releases/vMAJOR.MINOR`` (note the ``v``) containing + the code at the intended stage is created + 2. The commit is tagged with a descriptive message: ``git tag vMAJOR.MINOR.0 + -m 'short descriptive message here'`` (note the ``v``) + 3. Changes are pushed to the remote: + + .. code-block:: console + + $ git push origin releases/vMAJOR.MINOR + $ git push origin refs/tags/vMAJOR.MINOR.0 + +* To release a new **patch version**, the following procedure should be followed: + + 1. A commit with the patch is created on the relevant release branch + ``releases/vMAJOR.MINOR`` + 2. The commit is tagged: ``git tag vMAJOR.MINOR.PATCH`` (note the ``v``) + 3. Changes are pushed to the remote: + + .. code-block:: console + + $ git push origin releases/vMAJOR.MINOR + $ git push origin refs/tags/vMAJOR.MINOR.PATCH + +* To upload the release to the `Python Package Index + `_, a new release must be created through + `the GitHub interface `_, + associated to the just created tag. Usage of the "Generate release notes" + option is recommended. diff --git a/docs/source/index.rst b/docs/source/index.rst index 4dc2505..44ac39a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -41,3 +41,21 @@ Next steps manuals/index Package API reference + +.. toctree:: + :maxdepth: 1 + :caption: Related projects + + LEGEND Data Objects + Digital Signal Processing + pygama + +.. toctree:: + :maxdepth: 1 + :caption: Development + + Source Code + License + Citation + Changelog + developer