Update sphinx docs

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 43e141b2a80358f2f14479b8dd97ab3b
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_images/graphviz-076766984f34b93a9d82f4bb29530f62cfc702af.png.map

@@ -0,0 +1,2 @@
+<map id="allocation" name="allocation">
+</map>

_images/graphviz-8034e46f472445428ec0a3908c62f907b47614c3.png.map

@@ -0,0 +1,2 @@
+<map id="release" name="release">
+</map>

_images/graphviz-981eacfab8eb2a42215ddeb7564c51358af44bb0.png.map

@@ -0,0 +1,2 @@
+<map id="freelist" name="freelist">
+</map>

_images/graphviz-f3da9712e3905cb30d4ae47e7e62c2a1e0fece65.png.map

@@ -0,0 +1,2 @@
+<map id="G" name="G">
+</map>

_sources/developer/build.rst.txt

@@ -0,0 +1,48 @@
+Building and running the unit tests
+===================================
+
+x3d2 is in early development phase, and there is no main executable
+yet to be built.  However, currently implemented functionality is
+covered by unit tests, which you can build and run on you development
+machine.
+
+To build x3d2, you will need git, a fortran compiler and CMake, see
+:ref:`tooling`.
+
+Start by configuring the build directory:
+
+.. code-block:: console
+
+   $ cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
+
+To configure the build with the NVIDIA Fortran compiler, you can set
+the `FC` environment variable to the compiler executable.  If you
+specify an relative path, it must be present in your current `PATH`.
+
+.. code-block:: console
+
+   $ FC=nvfortran cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
+
+Setting the Fortran compiler to the NVIDIA Fortran compiler will
+automatically include the CUDA Fortran source files into the build
+tree, which are ignored by default.
+
+Once the build directory is configured, the tests can be built and run
+as follows:
+
+.. code-block:: console
+
+   $ cd build
+   $ make
+   $ make test
+
+Note that ``make test`` is only a launcher for the ``ctest``
+executable.  By default ``ctest`` does not show the output of test
+executables on failure.  If one of more tests fail, you probably want
+to run the tests with:
+
+.. code-block:: console
+
+   $ ctest --output-on-failure
+
+instead of ``make test``.

_sources/developer/contributing_guidelines.rst.txt

@@ -0,0 +1,145 @@
+Contributing guidelines
+=======================
+
+x3d2 is a collaborative project, open to all.  In order to enable
+effective collaboration, however, we ask that your contribution(s)
+comply with a set of ground rules.
+
+In a nutshell
+-------------
+
+- For any contribution not covered by an existing issue, **open an issue
+  first**.
+- Respect the commit format.  (:ref:`Install the git hook! <devenv-setup>`).
+- Only commit changes formatted with `fprettify`, using the project's
+  configuration.  (:ref:`Install the git hook! <devenv-setup>`).
+- Strive to contribute **small and focused Pull Requests with detailed
+  descriptions**.
+- Add (a) unit test(s) covering a new feature, or (a) regression
+  test(s) for a bug fix.
+
+Issues first
+------------
+
+Issues are opened as soon as possible, particularly before any
+significant implementation work is carried out or any pull request is
+opened.  Starting with issues greatly facilitates collaboration:
+
+- It encourages developers to write (and therefore think) about the
+  work they plan to achieve.
+- It helps maintaining a shared and up to date record of current work
+  (known bugs, current developments).
+- It helps coordination between developers by sign-posting who is
+  working on what, as well as what is not being worked on.
+- It allows discussions between developers on how to best fix the
+  issue or implement the described improvement(s).
+
+This doesn't mean that you should forbid yourself from exploratory
+prototyping until an issue has been opened. In fact, prototyping is
+often helpful to write the content of the issue.  On the other hand,
+do open an issue before commiting to a particular design or
+implementation.
+
+.. _commit-formatting:
+
+Format commits accordingly
+--------------------------
+
+Commits messages are formatted according to the conventional commits
+specification (v1.0.0).  Commit messages must respect the following
+structure::
+
+  <type>[optional scope]: <description>
+
+  [optional body]
+
+where `<type>` is one of `fix`, `feat`, `build`, `chore`, `ci`,
+`docs`, `style`, `refactor`, `perf` or `test`.
+
+Breaking changes are specified by adding an `!` before the colon `:`. Example::
+
+  fix(allocator)!: Return 1D arrays as data blocks
+
+  This is a breaking change because e.g. the allocator used to
+  return 3D data blocks.
+
+In addition, commit message header lines must not contain more than 68
+characters.  Lines in the commit message body cannot exceed 72
+characters.
+
+.. note::
+
+   Commit messages in x3d2 do not use footers as specified in the
+   conventional commit specs.  You are welcome to use footers in your
+   commit messages, but know that they hold no special place in the
+   commit format policy.
+
+A Git hook is provided to prevent you from registering non-conformant
+commit messages. See setting up your development environment.
+
+Fortran code formatting
+-----------------------
+
+Code formatting dictates things like indentation levels, number of
+whitespace between operators or use upper/lowercase characters for
+keywords.
+
+Because having to learn such project specific rules isn't terribily
+interesting, all Fortran code in x3d2 is formatted automatically using
+`fprettify <https://github.com/pseewald/fprettify>`_. Some non-default
+configuraiton options are specified in the project's `.fprettify.ini`
+file.
+
+Note that a a GitHub pull request will not be merged until all the
+associated code addtions conform to the formatting.
+
+The best way to deal with code formatting is to **automate it and
+forget about it**.  To do so, make sure you install the pre-commit
+hook into your local git repository, see .  This way, `fprettify` will
+run automatically each time you commit new changes.
+
+Pull requests and code review
+-------------------------------
+
+Code review is a fondamental part of x3d2's collaborative development.
+Particularly, GitHub pull requests must be approved by at least two
+maintainers before the associated commits are merged.  Code review allows for
+
+- Gatekeeping, by preventing the integration of changes that are not
+  up to standards, introducing bugs or potentially disruptive to
+  ongoing and/or future developments.
+- Knowledge transfer, by making sure that at least a couple of project
+  developers have an opportunity to study and understand the code to
+  be integrated.
+- Training, by giving new contributors opportunities to get feedback
+  and help, as well as chances to review contributions from more
+  experienced developers.
+
+Poor quality pull requests can however turn the code review process
+into a bottleneck or worse, lead to poor quality reviews. In order to
+facilitate the code review process, pull request must be both
+**focused and small** and have a **detailed description**.
+
+1. Pull requests should aim to merge a be coherent body of changes,
+   targeting a single aspect of an issue.  It is much prefereable to
+   fix an issue through multiple pull requests than one big
+   contribution.
+2. Pull requests should aim to merge a limited number of changes.  As
+   a rule of thumb, pull requests usually become much harder to review
+   beyond 10 changes.
+3. Pull requests should come with a detailed description containing:
+
+   - One or two sentences summing up the motivation for the changes.
+   - A link to the addressed issue(s).
+   - A summary of the changes.
+   - A technical description of the changes.
+
+   The description is important for archiving purposes, but most
+   importlantl in order to guide the work of reviewers.
+
+Note that the points above are guidelines as opposed to hard and fast
+rules.  For a given pull request, the amount of work required to
+review the changes will vary across reviewers.  Generally, however,
+please **empathise with your fellow contributors who are going to spend
+time reviewing your code**.  Aim to make their work easier, and they
+will do the same for you.

_sources/developer/contribution_workflow.rst.txt

@@ -0,0 +1,40 @@
+Overview of the contribution process
+====================================
+
+The graph below illustrates the general process for contributing code
+changes to x3d2:
+
+.. graphviz::
+
+   digraph G {
+       review[shape="diamond", label="Changes approved"]
+       commit[label="commit changes locally"]
+
+       PR[label="Open/update Pull Request"];
+
+       Idea -> "Open new issue" -> commit -> PR
+       PR -> review
+       review -> merge [label="yes"]
+       review -> commit [label=" no"]
+       "Pick existing issue" -> commit
+
+       {
+           rank=sink;
+           review; merge
+       }
+   }
+
+Contributions are accepeted in the form of pull requests targeting the
+`main` branch on the x3d2 GitHub repository.  See `(GitHub docs)
+Creating a pull request
+<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`_.
+
+By default your GitHub account will not be able to push changes to the
+x3d2 repo, and you will have to open the pull request from a fork. See
+`(GitHub docs) Creating a pull request from a fork
+<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_.
+
+Note that the whole process is **driven by issues**. If you found a
+bug not currently referenced by an existing issue, or have an idea on
+how to improve a part of x3d2, please open a new item on the issue
+tracker before opening a pull request.

_sources/developer/dev_environment.rst.txt

@@ -0,0 +1,35 @@
+.. _devenv-setup:
+
+Setting up for development
+==========================
+
+0. To begin with, make sure you have the right tools installed by going
+   through the :ref:`required tooling <tooling>`.
+
+1. Download the x3d2 repository from GitHub::
+
+    $ git clone [email protected]:xcompact3d/x3d2.git
+    $ cd x3d2/
+
+  The following commands assume that your shell's current directory is
+  the root of the `x3d2` repository.
+
+2. Install the `pre-commit` Git hook into your project-local
+   configuration::
+
+     $ cp githooks/pre-commit .git/hooks/
+     $ chmod +x .git/hooks/pre-commit
+
+   This Git hook will cause the automatic formatting of all fortran
+   files staged in your commit, using `fprettify`.
+
+3. Install the `commit-msg` Git hook into your project-local
+   configuration::
+
+     $ cp githooks/commit-msg .git/hooks/
+     $ chmod +x .git/hooks/commit-msg
+
+   This Git hook will automatically check your commit message against
+   the commit message format, based on the conventional commits
+   specification. See :ref:`the contribution guidelines
+   <commit-formatting>`.

_sources/developer/index.rst.txt

@@ -0,0 +1,36 @@
+Contributing to x3d2
+====================
+
+Fixed a bug?  Have an idea for improving x3d2? x3d2 is developed in
+the open with a license that allows anyone to:
+
+- Run the program as they wish, for any purpose.
+- Access and study its source code, and making changes to it.
+- Redistribute copies (source or binary).
+- Distribute copies of your modified versions (source or binary).
+
+Particularly, we encourage developers to contribute their changes back
+to the x3d2 project. The following sections describe the process for
+doing so.
+
+.. toctree::
+   :maxdepth: 1
+
+   contribution_workflow
+   tooling
+   dev_environment
+   build
+   contributing_guidelines
+   style
+   writing_docs
+
+If you are looking to take part in the project but don't have anything
+specific in mind, you could consider:
+
+- Reporting (a) bug(s), suggest improvement(s) or share a user experience.
+- Adding documentation or improving the current one.
+- Working on fixing issues or implementing new features.
+
+In any of the cases above, your entry point should be the `issue
+tracker <https://github.com/xcompact3d/x3d2/issues>`_ -- either to
+pick an existing issue to work on or to create a new one.