project_setup.md

Project Setup

Here we provide some details about the project setup. Most of the choices are explained in the guide. Links to the relevant sections are included below. Feel free to remove this text when the development of the software package takes off.

For a quick reference on software development, we refer to the software guide checklist.

Python versions

This repository is set up with Python versions:

• 3.11
• 3.12

Add or remove Python versions based on project requirements. See the guide for more information about Python versions.

Package management and dependencies

For installing the dependencies and package management, micromamba and poetry have been used.

The dependencies are listed in the pyproject.toml file under the section [tool.poetry.dependencies] and [tool.poetry.group.dev.dependencies].

Packaging/One command install

To create a new environment, use the micromamba:

micromamba create -n rcx-tk poetry
micromamba activate rcx-tk

To install all dependencies specified in the pyproject.toml file, use poetry:

poetry install

Testing and code coverage

• Tests should be put in the tests folder.
• The tests folder contains:
  • Example tests that you should replace with your own meaningful tests (file: test_my_module.py)
• The testing framework used is PyTest
  • PyTest introduction
  • PyTest is listed as a development dependency
  • This is configured in pyproject.toml
• The project uses GitHub action workflows to automatically run tests on GitHub infrastructure against multiple Python versions
  • Workflows can be found in .github/workflows
• Relevant section in the guide

Documentation

• Documentation should be put in the docs/ directory. The contents have been generated using sphinx-quickstart (Sphinx version 1.6.5).
• We recommend writing the documentation using Restructured Text (reST) and Google style docstrings.
  • Restructured Text (reST) and Sphinx CheatSheet
  • Google style docstring examples.
• The documentation is set up with the ReadTheDocs Sphinx theme.
  • Check out its configuration options.
• AutoAPI is used to generate documentation for the package Python objects.
• .readthedocs.yaml is the ReadTheDocs configuration file. When ReadTheDocs is building the documentation this package and its development dependencies are installed so the API reference can be rendered.
• Relevant section in the guide

Coding style conventions and code quality

• Relevant section in the NLeSC guide and README.dev.md.

Continuous code quality

Sonarcloud is used to perform quality analysis and code coverage report

• sonar-project.properties is the SonarCloud configuration file
• .github/workflows/sonarcloud.yml is the GitHub action workflow which performs the SonarCloud analysis

Package version number

• We recommend using semantic versioning.
• For convenience, the package version is stored in a single place: rcx-tk/pyproject.toml under the tool.bumpversion header.
• Don't forget to update the version number before making a release!

Logging

• We recommend using the logging module for getting useful information from your module (instead of using print).
• The project is set up with a logging example.
• Relevant section in the guide

CHANGELOG.md

• Document changes to your software package
• Relevant section in the guide

CITATION.cff

• To allow others to cite your software, add a CITATION.cff file
• It only makes sense to do this once there is something to cite (e.g., a software release with a DOI).
• Follow the making software citable section in the guide.

CODE_OF_CONDUCT.md

• Information about how to behave professionally
• Relevant section in the guide

CONTRIBUTING.md

• Information about how to contribute to this software package
• Relevant section in the guide

MANIFEST.in

• List non-Python files that should be included in a source distribution
• Relevant section in the guide

NOTICE

• List of attributions of this project and Apache-license dependencies
• Relevant section in the guide