Update documentation

.github/workflows/test.yml

@@ -53,7 +53,6 @@ jobs:
       - name: Create documentation
         run: |
           cmake --build build --target documentation
-      # - name: Create and verify release
-      #   run: |
-      #     py_interpreter="${{ steps.py.outputs.python-path }}"
-      #     PYTHONPATH=source/package ${py_interpreter} environment/script/create_and_verify_release.py ./build
+      - name: Create package
+        run: |
+          cmake --build build --target package

CMakeLists.txt

@@ -82,18 +82,6 @@ add_custom_target(package
                 ${CMAKE_CURRENT_SOURCE_DIR}
 )
 
-add_custom_target(installer
-    VERBATIM
-    COMMAND
-        ${CMAKE_COMMAND} -E env "PYTHONPATH=${AP_PYTHONPATH}"
-            ${PyInstaller_EXECUTABLE}
-                --noconfirm
-                adaptation_pathways.spec
-    DEPENDS
-        adaptation_pathways.spec
-        # icon
-)
-
 add_custom_target(release
     # VERBATIM
     COMMAND
@@ -124,6 +112,18 @@ add_dependencies(release
     package
 )
 
+add_custom_target(installer
+    VERBATIM
+    COMMAND
+        ${CMAKE_COMMAND} -E env "PYTHONPATH=${AP_PYTHONPATH}"
+            ${PyInstaller_EXECUTABLE}
+                --noconfirm
+                adaptation_pathways.spec
+    DEPENDS
+        adaptation_pathways.spec
+        # icon
+)
+
 add_custom_target(installer_release
     VERBATIM
     COMMAND

documentation/CMakeLists.txt

@@ -1,3 +1,6 @@
+add_subdirectory(develop)
+add_subdirectory(use)
+
 configure_file(
     conf.py.in
     conf.py
@@ -12,14 +15,6 @@ foreach(name IN ITEMS changelog glossary index)
     )
 endforeach()
 
-foreach(name IN ITEMS develop test use)
-    configure_file(
-        ${name}/index.rst
-        ${name}/index.rst
-        COPYONLY
-    )
-endforeach()
-
 set(AP_SPHINX_SOURCE_DIR ${CMAKE_CURRENT_BINARY_DIR})
 set(AP_SPHINX_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/html)
 

documentation/conf.py.in

@@ -14,6 +14,7 @@ project = "@CMAKE_PROJECT_NAME@"
 copyright = "2024, TODO"
 author = ", ".join(
     [
+        # TODO Add everybody
         "Marjolijn Haasnoot (Deltares, NL)",
         "Willem van Deursen (Carthago Consultancy, NL)",
         "Kor de Jong (Geoneric, NL)",

documentation/develop/CMakeLists.txt

@@ -0,0 +1,7 @@
+foreach(name IN ITEMS environment git index release)
+    configure_file(
+        ${name}.rst
+        ${name}.rst
+        COPYONLY
+    )
+endforeach()

documentation/develop/environment.rst

@@ -0,0 +1,134 @@
+Development environment
+=======================
+
+Clone repository
+----------------
+
+If you want to help improve the software, the first thing you need to do is clone the Git
+repository that contains the source code:
+
+.. code-block:: bash
+
+   cd ...  # Prefix of some location that should end up containing the repository clone
+   git clone git@github.com:Deltares-research/PathwaysGenerator.git
+
+This assumes that you have write access to the main Git repository, which may not be the case. It
+is good practice to contribute to a software project by performing the following steps:
+
+#. Fork the repository you want to contribute to to your own Github organization
+#. Clone the forked version of the main repository
+#. Make changes in a branch
+#. Push this branch to your fork of the main repository
+#. Create a pull-request (PR)
+
+Once finished creating the PR, someone with write access to the main repository (could be you
+as well) can review the changes and eventually merge them.
+
+* `Contributing to a project tutorial
+  <https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project>`_
+
+
+Setup environment
+-----------------
+
+The steps for setting up a development environment are as follows:
+
+#. Create and activate a new virtual environment
+#. Install all required Python and non-Python packages
+#. Install :ref:`pre-commit hooks <sec-pre-commit>`
+#. Verify everything works
+
+In commands:
+
+.. code-block:: bash
+
+   cd adaptation_pathways  # The repository clone
+   python3 -m venv env
+   source env/bin/activate
+   pip3 install --upgrade pip
+
+   # Install software needed to help develop our software:
+   pip3 install -r environment/configuration/requirements.txt -r environment/configuration/requirements-dev.txt
+
+   # Install handy tools that will keep our code in good shape:
+   pre-commit install
+   # Note: commit .pre-commit-config.yaml if any hooks actually got updated
+   pre-commit autoupdate
+
+   source/script/ap_pathway_generator.py --help
+
+
+The project contains code for generating :ref:`targets <sec-cmake>`, like documentation and the
+installation package. Create a new directory for storing these. It is best to create this directory
+outside of the source directory. CMake is used to generate build scripts that will do the actual
+work. We use the Ninja build tool here, but you can use any build tool supported by CMake.
+
+.. code-block:: bash
+
+   # Assuming we are in the adaptation_pathways source directory...
+
+   mkdir ../build
+   cd ../build
+   cmake -S ../adaptation_pathways -G Ninja
+
+   # Execute the tests
+   ninja test
+
+   # Generate the documentation
+   ninja documentation
+
+   # Create the package
+   ninja package
+
+   # List all targets
+   ninja -t targets
+
+
+Make some changes
+-----------------
+
+Here you can find an example workflow for submitting changes to the main repository. The commands
+shown work in a Bash shell and use command-line Git. In case you use other software in your
+development environment (e.g. Visual Studio Code) things will work differently, but the gist /
+steps will be the same.
+
+.. code-block:: bash
+
+   # Assuming we are in the adaptation_pathways source directory...
+   # Assuming the main branch is up to date with the main repository's main branch...
+
+   # Assuming we will work on solving Github issue #5...
+   # Create a new branch named after the issue number: Github issue number 5
+   git checkout -b gh5
+
+   # Make the changes..
+   # ...
+
+   # Push branch to your own fork
+   git push -u origin gh5
+
+In the Github page for your fork of the repository, there will now be button you can press
+for creating the PR. Use the title of the Github issue that got solved for the title of the
+PR. Add a comment similar to "Solves #5" to the PR. This will make sure that the issue gets
+automatically close once the PR gets merged.
+
+After making changes, verify locally that the unit tests still run and the code is still in
+good shape. This will also be checked by the Github workflows setup for the repository. Doing it
+locally results in a smoother process because it is more likely that your changes won't result
+in workflows to fail.
+
+.. code-block:: bash
+
+   # Run unit tests
+   ctest --test-dir build --output-on-failure
+
+   # Alternatively, if you use Ninja
+   ninja test
+
+   # Alternatively, if you use GNU Make
+   make test
+
+   # Etc ;-)
+
+If you have setup the pre-commit hooks correctly, various checks will be performed on the
+changed files before they are actually committed.

documentation/develop/git.rst

@@ -0,0 +1,2 @@
+Use of Git
+==========