diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index ff6cdc6..e2524f2 100644 --- a/.github/workflows/test.yml +++ b/.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 diff --git a/CMakeLists.txt b/CMakeLists.txt index 58d933b..03e71ba 100644 --- a/CMakeLists.txt +++ b/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 diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt index 8c7eb23..d0bfb5c 100644 --- a/documentation/CMakeLists.txt +++ b/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) diff --git a/documentation/conf.py.in b/documentation/conf.py.in index f9b44a5..0fbf981 100644 --- a/documentation/conf.py.in +++ b/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)", diff --git a/documentation/develop/CMakeLists.txt b/documentation/develop/CMakeLists.txt new file mode 100644 index 0000000..675485d --- /dev/null +++ b/documentation/develop/CMakeLists.txt @@ -0,0 +1,7 @@ +foreach(name IN ITEMS environment git index release) + configure_file( + ${name}.rst + ${name}.rst + COPYONLY + ) +endforeach() diff --git a/documentation/develop/environment.rst b/documentation/develop/environment.rst new file mode 100644 index 0000000..2cac333 --- /dev/null +++ b/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 + `_ + + +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 ` +#. 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 `, 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. diff --git a/documentation/develop/git.rst b/documentation/develop/git.rst new file mode 100644 index 0000000..b59f921 --- /dev/null +++ b/documentation/develop/git.rst @@ -0,0 +1,2 @@ +Use of Git +========== diff --git a/documentation/develop/index.rst b/documentation/develop/index.rst index 49b970c..80ea7e8 100644 --- a/documentation/develop/index.rst +++ b/documentation/develop/index.rst @@ -4,175 +4,14 @@ Develop .. toctree:: :maxdepth: 1 + Development environment + Create a release + Use of Git API <../api/modules> Index <../genindex> Examples -Development environment ------------------------ - -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 - # TODO Fix url once repository is moved to a shared location - git clone ssh://git@some_server:some_port/some_organization/adaptation_pathways.git - -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 ` -#. 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 `, 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 - - -Create and test a package -------------------------- -Creating a package and inspecting its contents can be done as follows: - -.. code-block:: bash - - # In build directory - ninja - ninja package - tar -tf dist/adaptation_pathways-1.2.3.tar.gz - unzip -l dist/adaptation_pathways-1.2.3-py3-none-any.whl - -Creating a package (``ninja package``) results in a Wheel file in the ``dist`` directory in -the project's output directory. The next commands can be used to test the package. - -.. code-block:: bash - - python3 -m venv ap_test - source ap_test/bin/activate - pip install --upgrade pip - pip install -f dist adaptation_pathways - adaptation_pathways --help - -After testing the package, new versions of the package can be installed like this: - -.. code-block:: bash - - pip install upgrade -f dist adaptation_pathways - - -Release a package ------------------ - -.. warning:: - - Double-check that all changes are committed. - - -Python package -~~~~~~~~~~~~~~ - -#. Create zip with Python Wheel package and the documentation, and verify the contents are OK: - - .. code-block:: bash - - # In build directory - create_and_verify_release.py . - - .. warning:: - - Do not release the package when this command fails. - - Output is stored in ``adaptation_pathways-1.2.3.zip``. - -#. Copy the zip to a location users can find it. - - -Pathway generator -~~~~~~~~~~~~~~~~~ - -#. On all platforms the users care about, create a zip containing the pathway generator. This - zip contains a directory with all requirements needed to use the software. It is portable: - users can install multiple versions, anywhere they like. - - .. code-block:: bash - - # In build directory - ninja installer_release - - Output is stored in ``pathway_generator--.zip`` - -#. Copy the zip to a location users can find it. - -.. note:: - - On Windows, executing the pathway generator executable may fail because the virus scanner - thinks it contains a virus. The virus scanner is wrong. - - -Wrap-up -~~~~~~~ - -#. Create and push a tag. - - .. code-block:: bash - - # In source directory - git tag -a v1.2.3 -m"Release that adds cool features and solves all problems" - git push origin v1.2.3 - -#. Bump the version number in these files: - - - ``CMakeLists.txt`` - - ``pyproject.toml`` - - ``source/package/adaptation_pathways/version.py`` - -#. Add a section for the upcoming version to the :ref:`changelog `: ``documentation/changelog.rst``. - - Notes on software we use ------------------------ diff --git a/documentation/develop/release.rst b/documentation/develop/release.rst new file mode 100644 index 0000000..9f82e83 --- /dev/null +++ b/documentation/develop/release.rst @@ -0,0 +1,100 @@ +Release a version +================= + +Create and test a package +------------------------- +Creating a package and inspecting its contents can be done as follows: + +.. code-block:: bash + + # In build directory + ninja + ninja package + tar -tf dist/adaptation_pathways-1.2.3.tar.gz + unzip -l dist/adaptation_pathways-1.2.3-py3-none-any.whl + +Creating a package (``ninja package``) results in a Wheel file in the ``dist`` directory in +the project's output directory. The next commands can be used to test the package. + +.. code-block:: bash + + python3 -m venv ap_test + source ap_test/bin/activate + pip install --upgrade pip + pip install -f dist adaptation_pathways + adaptation_pathways --help + +After testing the package, new versions of the package can be installed like this: + +.. code-block:: bash + + pip install upgrade -f dist adaptation_pathways + + +Release a package +----------------- + +.. warning:: + + Double-check that all changes are committed. + + +Python package +~~~~~~~~~~~~~~ + +#. Create zip with Python Wheel package and the documentation, and verify the contents are OK: + + .. code-block:: bash + + # In build directory + create_and_verify_release.py . + + .. warning:: + + Do not release the package when this command fails. + + Output is stored in ``adaptation_pathways-1.2.3.zip``. + +#. Copy the zip to a location users can find it. + + +Pathway generator +~~~~~~~~~~~~~~~~~ + +#. On all platforms the users care about, create a zip containing the pathway generator. This + zip contains a directory with all requirements needed to use the software. It is portable: + users can install multiple versions, anywhere they like. + + .. code-block:: bash + + # In build directory + ninja installer_release + + Output is stored in ``pathway_generator--.zip`` + +#. Copy the zip to a location users can find it. + +.. note:: + + On Windows, executing the pathway generator executable may fail because the virus scanner + thinks it contains a virus. The virus scanner is wrong. + + +Wrap-up +~~~~~~~ + +#. Create and push a tag. + + .. code-block:: bash + + # In source directory + git tag -a v1.2.3 -m"Release that adds cool features and solves all problems" + git push origin v1.2.3 + +#. Bump the version number in these files: + + - ``CMakeLists.txt`` + - ``pyproject.toml`` + - ``source/package/adaptation_pathways/version.py`` + +#. Add a section for the upcoming version to the :ref:`changelog `: ``documentation/changelog.rst``. diff --git a/documentation/index.rst b/documentation/index.rst index 7d8b8a4..949b28a 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -1,15 +1,12 @@ Adaptation Pathways =================== -What do you want to do? - .. toctree:: :maxdepth: 1 :caption: Contents: - Use the package - Test the package - Develop the package + User manual + Developer manual Glossary Changelog diff --git a/documentation/use/CMakeLists.txt b/documentation/use/CMakeLists.txt new file mode 100644 index 0000000..dbd4079 --- /dev/null +++ b/documentation/use/CMakeLists.txt @@ -0,0 +1,7 @@ +foreach(name IN ITEMS index get_started) + configure_file( + ${name}.rst + ${name}.rst + COPYONLY + ) +endforeach() diff --git a/documentation/test/index.rst b/documentation/use/get_started.rst similarity index 76% rename from documentation/test/index.rst rename to documentation/use/get_started.rst index f09c8cc..2c0e964 100644 --- a/documentation/test/index.rst +++ b/documentation/use/get_started.rst @@ -1,28 +1,29 @@ -Test -==== +Get started +=========== -The software can be tested by performing these steps in turn: +The software can be used by performing these steps in turn: #. Create and activate a new virtual environment. There are multiple options for this. Below we show how to setup a virtual environment using Python's built-in venv module and using Conda. - - .. note:: - - Python's built-in venv module and Conda (and others) are alternatives with which you can - achieve the same thing: create one or more virtual environments to install Python packages in. - You don't need to use Python's venv module if you work with Conda, and vice versa. - #. Install all required Python packages -#. Test the software +#. Use the software #. Remove the virtual environment -This procedure will leave no traces on your computer. If you intent to test the software regularly, -you can keep the virtual environment as is, and install the updated version of the software later. +This procedure will leave no traces on your computer. If you intent to use the software regularly, +you can keep the virtual environment as is, and install any updated versions of the software later. Create a virtual environment ---------------------------- +Python's built-in venv module and Conda (and others) are alternatives with which you can +achieve the same thing: create one or more virtual environments to install Python packages in. +You don't need to use Python's venv module if you work with Conda, and vice versa. + +In the examples below, a virtual environment called ap_test is created. You can of course pick any +other name for the environment. + + Using venv ~~~~~~~~~~ @@ -61,8 +62,8 @@ The software is packaged as a Python wheel file. The pip command can be used to pip3 install -f dist adaptation_pathways -Test software -------------- +Use software +------------ Once the software is installed correctly, the following should work: diff --git a/documentation/use/index.rst b/documentation/use/index.rst index ba24680..667afaf 100644 --- a/documentation/use/index.rst +++ b/documentation/use/index.rst @@ -4,4 +4,5 @@ Use .. toctree:: :maxdepth: 1 + Get started Examples