Merge pull request graphnet-team#696 from graphnet-team/doc_2nd_attempt

First Documentation Update

.github/actions/install/action.yml

@@ -18,7 +18,7 @@ inputs:
     description: "The requirements file depends on the hardware, i.e., CPU, GPU, or macOS"
     required: true
     default: "cpu"
-    options: ["cpu", "gpu", "macos"]
+    options: ["cpu", "cu118", "cu121", "macos"]
 
 runs:
   using: "composite"

.gitignore

@@ -130,9 +130,10 @@ dmypy.json
 
 # Documentation
 docs/build/html
-docs/**/*.rst
+docs/source/api/*.rst
 docs/source/*.md
 
+
 # Badges
 assets/badges
 

docs/source/about/about.rst

@@ -0,0 +1,37 @@
+.. include:: ../substitutions.rst
+
+About
+============
+
+|graphnet|\ GraphNeT is an open-source Python framework aimed at providing high quality, user friendly, end-to-end functionality to perform reconstruction tasks at neutrino telescopes using deep learning. |graphnet|\ GraphNeT makes it fast and easy to train complex models that can provide event reconstruction with state-of-the-art performance, for arbitrary detector configurations, with inference times that are orders of magnitude faster than traditional reconstruction techniques.
+|graphnet|\ GraphNeT provides a common, detector agnostic framework for ML developers and physicists that wish to use the state-of-the-art tools in their research. By uniting both user groups, |graphnet|\ GraphNeT aims to increase the longevity and usability of individual code contributions from ML developers by building a general, reusable software package based on software engineering best practices, and lowers the technical threshold for physicists that wish to use the most performant tools for their scientific problems.
+
+Usage
+-----
+
+|graphnet|\ GraphNeT comprises a number of modules providing the necessary tools to build workflows from ingesting raw training data in domain-specific formats to deploying trained models in domain-specific reconstruction chains, as illustrated in [the Figure](flowchart).
+
+.. _flowchart:
+.. figure:: ../../../paper/flowchart.png
+
+    High-level overview of a typical workflow using |graphnet|\ GraphNeT: :code:`graphnet.data` enables converting domain-specific data to industry-standard, intermediate file formats and reading this data; :code:`graphnet.models` allows for configuring and building complex models using simple, physics-oriented components; :code:`graphnet.training` manages model training and experiment logging; and finally, :code:`graphnet.deployment` allows for using trained models for inference in domain-specific reconstruction chains.
+
+:code:`graphnet.models` provides modular components subclassing :code:`torch.nn.Module`, meaning that users only need to import a few existing, purpose-built components and chain them together to form a complete model. ML developers can contribute to |graphnet|\ GraphNeT by extending this suite of model components — through new layer types, physics tasks, graph connectivities, etc. — and experiment with optimising these for different reconstruction tasks using experiment tracking.
+
+These models are trained using :code:`graphnet.training` on data prepared using :code:`graphnet.data`, to satisfy the high I/O loads required when training ML models on large batches of events, which domain-specific neutrino physics data formats typically do not allow.
+
+Trained models are deployed to a domain-specific reconstruction chain, yielding predictions, using the components in :code:`graphnet.deployment`. This can either be through model files or container images, making deployment as portable and dependency-free as possible.
+
+By splitting up the model development as in :numref:`flowchart`, |graphnet|\ GraphNeT allows physics users to interface only with high-level building blocks or pre-trained models that can be used directly in their reconstruction chains, while allowing ML developers to continuously improve and expand the framework’s capabilities.
+
+
+Acknowledgements
+----------------
+
+
+.. image:: ../../../assets/images/eu-emblem.jpg
+    :width: 150
+
+This project has received funding from the European Union’s Horizon 2020 research and innovation programme under the Marie Skłodowska-Curie grant agreement No. 890778.
+
+The work of Rasmus Ørsøe was partly performed in the framework of the PUNCH4NFDI consortium supported by DFG fund "NFDI 39/1", Germany.

docs/source/conf.py

@@ -46,6 +46,9 @@
     "myst_parser",
 ]
 
+# Figure references
+numfig = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/source/contribute/contribute.rst

@@ -0,0 +1,54 @@
+.. include:: ../substitutions.rst
+
+Contributing To GraphNeT\ |graphnet-header|
+===========================================
+To make sure that the process of contributing is as smooth and effective as possible, we provide a few guidelines in this contributing guide that we encourage contributors to follow.
+
+GitHub issues
+-------------
+
+Use `GitHub issues <https://github.com/graphnet-team/graphnet/issues>`_ for tracking and discussing requests and bugs. If there is anything you'd wish to contribute, the best place to start is to create a new issues and describe what you would like to work on. Alternatively you can assign open issues to yourself, to indicate that you would like to take ownership of a particular task. Using issues actively in this way ensures transparency and agreement on priorities. This helps avoid situations with a lot of development effort going into a feature that e.g. turns out to be outside of scope for the project; or a specific solution to a problem that could have been better solved differently.
+
+Pull requests
+-------------
+
+Develop code in a fork of the `main repo <https://github.com/graphnet-team/graphnet>`_. Make contributions in dedicated development/feature branches on your forked repositories, e.g. if you are implementing a specific :code:`GraphDefinition` class you could create a branch named :code:`add-euclidean-graph-definition` on your own fork.
+
+Create pull requests from your development branch into :code:`graphnet-team/graphnet:main` to contribute to the project. **To be accepted,** pull requests must:
+
+* pass all automated checks,
+
+* be reviewed by at least one other contributor. These reviews should check for:
+
+  #. standard python coding conventions, e.g. `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_
+
+  #. docstring (Google-style) and type hinting as necessary
+
+  #. unit tests as necessary
+
+  #. clean coding practices, see e.g. `here <https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988cf8d29>`_. 
+
+Conventions
+-----------
+
+This repository aims to support python 3 version that are actively supported (currently :code:`>=3.8`). Standard python coding conventions should be followed:
+
+* Adhere to `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_  `black <https://black.readthedocs.io/>`_
+* Use `pylint <https://www.pylint.org/>`_ / `flake8 <https://flake8.pycqa.org/>`_ and `black <https://black.readthedocs.io/>`_ to ensure as clean and well-formatted code as possible
+* When relevant, adhere to `clean code practices <https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988cf8d29>`_
+
+Code quality
+------------
+
+To ensure consistency in code style and adherence to select best practices, we **require** that all developers use :code:`black`, :code:`flake8`, :code:`mypy`, :code:`pydocstyle`, and :code:`docformatter` for automatically formatting and checking their code. This can conveniently be done using pre-commit hooks. To set this up, first make sure that you have installed the :code:`pre-commit` python package. It is included when installing |graphnet|\ GraphNeT with the :code:`develop` tag, i.e., :code:`pip install -e .[develop]`. Then, do
+
+.. code-block:: bash
+   
+   pre-commit install
+
+
+Then, everytime you commit a change, your code and docstrings will automatically be formatted using :code:`black` and :code:`docformatter`, while :code:`flake8`, :code:`mypy`, and :code:`pydocstyle` will check for errors and adherence to PEP8, PEP257, and static typing. See an illustration of the concept below:
+
+.. image:: ../../../assets/images/precommit_pipeline.png
+
+Image source: https://ljvmiranda921.github.io/notebook/2018/06/21/precommits-using-black-and-flake8/

docs/source/index.rst

@@ -5,6 +5,9 @@
    :maxdepth: 1
    :hidden:
 
-   install
-   contribute
-   api/graphnet.rst
+
+   installation/install.rst
+   api/graphnet.rst
+   about/about.rst
+   contribute/contribute.rst
+