First version of documentation (#18)

Documentation web page
---------
Co-authored-by: Helen Theissen <[email protected]>
Co-authored-by: Jesper Dramsch <[email protected]>

CHANGELOG.md

@@ -18,6 +18,8 @@ Keep it human-readable, your future self will thank you!
 - added downstream-ci pipeline and cd-pypi reusable workflow
 - Changelog release updater
 
+- Create package documentation.
+
 ### Changed
 - fix: added support for Python3.9.
 - fix: bug in graph cleaning method

docs/_static/hetero_data_graph.txt

@@ -0,0 +1,30 @@
+HeteroData(
+  data={
+    x=[40320, 2],  # coordinates in radians (lat in [-pi/2, pi/2], lon in [0, 2pi])
+    node_type='ZarrDatasetNodes',
+    area_weight=[40320, 1],
+  },
+  hidden={
+    x=[10242, 2],  # coordinates in radians (lat in [-pi/2, pi/2], lon in [0, 2pi])
+    node_type='TriNodes',
+    area_weight=[10242, 1],
+  },
+  (data, to, hidden)={
+    edge_index=[2, 62980],
+    edge_type='CutOffEdges',
+    edge_length=[62980, 1],
+    edge_dirs=[62980, 2],
+  },
+  (hidden, to, hidden)={
+    edge_index=[2, 81900],
+    edge_type='MultiScaleEdges',
+    edge_length=[81900, 1],
+    edge_dirs=[81900, 2],
+  },
+  (hidden, to, data)={
+    edge_index=[2, 120960],
+    edge_type='KNNEdges',
+    edge_length=[120960, 1],
+    edge_dirs=[120960, 2],
+  }
+)

docs/cli/create.rst

@@ -0,0 +1,15 @@
+.. _cli-create:
+
+======
+create
+======
+
+Use this command to create a graph from a recipe file.
+
+The syntax of the recipe file is described in :doc:`building graphs <../graphs/introduction>`.
+
+.. argparse::
+    :module: anemoi.graphs.__main__
+    :func: create_parser
+    :prog: anemoi-graphs
+    :path: create

docs/cli/describe.rst

@@ -0,0 +1,15 @@
+.. _cli-describe:
+
+========
+describe
+========
+
+Use this command to describe a graph stored in your filesystem. It will print graph information to the console.
+
+The syntax of the recipe file is described in :doc:`building graphs <../graphs/introduction>`.
+
+.. argparse::
+    :module: anemoi.graphs.__main__
+    :func: create_parser
+    :prog: anemoi-graphs
+    :path: describe

docs/cli/inspect.rst

@@ -0,0 +1,15 @@
+.. _cli-inspect:
+
+========
+inspect
+========
+
+Use this command to inspect a graph stored in your filesystem.
+
+The syntax of the recipe file is described in :doc:`building graphs <../graphs/introduction>`.
+
+.. argparse::
+    :module: anemoi.graphs.__main__
+    :func: create_parser
+    :prog: anemoi-graphs
+    :path: inspect

docs/cli/introduction.rst

@@ -0,0 +1,29 @@
+.. _cli-introduction:
+
+=============
+Introduction
+=============
+
+When you install the `anemoi-graphs` package, this will also install command line tool
+called ``anemoi-graphs`` which can be used to design and inspect weather graphs.
+
+The tool can provide help with the ``--help`` options:
+
+.. code-block:: bash
+
+    % anemoi-graphs --help
+
+The commands are:
+
+.. toctree::
+    :maxdepth: 1
+
+    create
+    describe
+    inspect
+
+.. argparse::
+    :module: anemoi.graphs.__main__
+    :func: create_parser
+    :prog: anemoi-graphs
+    :nosubcommands:

docs/dev/code_structure.rst

@@ -0,0 +1,81 @@
+.. _dev-code_structure:
+
+################
+ Code Structure
+################
+
+Understanding and maintaining the code structure is crucial for
+sustainable development of Anemoi Graphs. This guide outlines best
+practices for contributing to the codebase.
+
+******************************
+ Subclassing for New Features
+******************************
+
+When creating a new feature, the recommended practice is to subclass
+existing base classes rather than modifying them directly. This approach
+preserves functionality for other users while allowing for
+customization.
+
+Example:
+========
+
+In `anemoi/graphs/nodes/builder.py`, the `BaseNodeBuilder` class serves
+as a foundation to define new sets of nodes. New node builders should
+subclass this base class.
+
+*******************
+ File Organization
+*******************
+
+When developing multiple new functions for a feature:
+
+#. Create a new file in the folder (e.g.,
+   `edges/builder/<new_edge_builder>.py`) to avoid confusion with base
+   functions.
+
+#. Group related functionality together for better organization and
+   maintainability.
+
+********************************
+ Version Control Best Practices
+********************************
+
+#. Always use pre-commit hooks to ensure code quality and consistency.
+#. Never commit directly to the `develop` branch.
+#. Create a new branch for your feature or bug fix, e.g.,
+   `feature/<feature_name>` or `bugfix/<bug_name>`.
+#. Submit a Pull Request from your branch to `develop` for peer review
+   and testing.
+
+******************************
+ Code Style and Documentation
+******************************
+
+#. Follow PEP 8 guidelines for Python code style, the pre-commit hooks
+   will help enforce this.
+#. Write clear, concise docstrings for all classes and functions using
+   the Numpy style.
+#. Use type hints to improve code readability and catch potential
+   errors.
+#. Add inline comments for complex logic or algorithms.
+
+*********
+ Testing
+*********
+
+#. Write unit tests for new features using pytest.
+#. Ensure all existing tests pass before submitting a Pull Request.
+#. Aim for high test coverage, especially for critical functionality.
+
+****************************
+ Performance Considerations
+****************************
+
+#. Profile your code to identify performance bottlenecks.
+#. Optimize critical paths and frequently called functions.
+#. Consider using vectorized operations when working with large
+   datasets.
+
+By following these guidelines, you'll contribute to a maintainable and
+robust codebase for Anemoi Graphs.

docs/dev/contributing.rst

@@ -0,0 +1,151 @@
+.. _dev-contributing:
+
+##############
+ Contributing
+##############
+
+Thank you for your interest in contributing to Anemoi Graphs! This guide
+will help you get started with the development process.
+
+****************************************
+ Setting Up the Development Environment
+****************************************
+
+#. Clone the repository:
+
+   .. code:: bash
+
+      git clone https://github.com/ecmwf/anemoi-graphs/
+      cd anemoi-graphs
+
+#. Install dependencies:
+
+   .. code:: bash
+
+      # For all dependencies
+      pip install -e .
+
+      # For development dependencies
+      pip install -e '.[dev]'
+
+#. (macOS only) Install pandoc for documentation building:
+
+   .. code:: bash
+
+      brew install pandoc
+
+******************
+ Pre-Commit Hooks
+******************
+
+We use pre-commit hooks to ensure code quality and consistency. To set
+them up:
+
+#. Install pre-commit hooks:
+
+   .. code:: bash
+
+      pre-commit install
+
+#. Run hooks on all files to verify installation:
+
+   .. code:: bash
+
+      pre-commit run --all-files
+
+*******************
+ Commit Guidelines
+*******************
+
+Ideally, open an issue for the feature or bug fix you're working on
+before starting development, to discuss the approach with maintainers.
+
+When committing code changes:
+
+#. Make small, focused commits with clear and concise messages.
+
+#. Follow the `Conventional Commits guidelines
+   <https://www.conventionalcommits.org/>`_, e.g., "feat:", "fix:",
+   "docs:", etc.
+
+#. Use present tense and imperative mood in commit messages (e.g., "Add
+   feature" not "Added feature").
+
+#. Reference relevant issue numbers in commit messages when applicable.
+
+#. Update the ``CHANGELOG.md`` file with a human-friendly summary of
+   your changes.
+
+**********************
+ Pull Request Process
+**********************
+
+#. Create a new branch for your feature or bug fix.
+#. Make your changes and commit them using the guidelines above.
+#. Push your branch to your fork on GitHub.
+#. Open a Pull Request against the `develop` branch of the main
+   repository.
+#. Ensure all tests pass and the code adheres to the project's style
+   guidelines.
+#. Request a review from maintainers or other contributors.
+
+***************
+ Running Tests
+***************
+
+We use pytest for our test suite. To run tests:
+
+.. code:: bash
+
+   # Run all tests
+   pytest
+
+   # Run tests in a specific file
+   pytest tests/test_<file>.py
+
+Note: Some tests, like `test_gnn.py`, may run slower on CPU and are
+better suited for GPU execution.
+
+************************
+ Building Documentation
+************************
+
+You can build the documentation locally to preview changes before
+submitting a Pull Request. We use Sphinx for documentation.
+
+You can install the dependencies for building the documentation with:
+
+.. code:: bash
+
+   pip install '.[docs]'
+
+To build the documentation locally:
+
+.. code:: bash
+
+   cd docs
+   make html
+
+The generated documentation will be in `docs/_build/html/index.html`.
+
+*********************
+ Code Review Process
+*********************
+
+#. All code changes must be reviewed before merging.
+#. Address any feedback or comments from reviewers promptly.
+#. Once approved, a maintainer will merge your Pull Request.
+
+******************
+ Reporting Issues
+******************
+
+If you encounter a bug or have a feature request:
+
+#. Check the existing issues to avoid duplicates.
+#. If it's a new issue, create a detailed bug report or feature request.
+#. Use clear, descriptive titles and provide as much relevant
+   information as possible.
+
+Thank you for contributing to Anemoi Graphs! Your efforts help improve
+the project for everyone.