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.

Version control

Once your Python package is created, put it under version control! We recommend using git and github.

cd notebooks
git init
git add --all
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/puregome/notebooks

Go to https://github.com/puregome?tab=repositories and create a new repository named notebooks as an empty repository, then:

git push --set-upstream origin main

Python versions

This repository is set up with Python versions:

• 3.6
• 3.7
• 3.8
• 3.9

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

Package management and dependencies

You can use either pip or conda for installing dependencies and package management. This repository does not force you to use one or the other, as project requirements differ. For advice on what to use, please check the relevant section of the guide.

• Runtime dependencies should be added to setup.cfg in the install_requires list under [options].
• Development dependencies should be added to setup.cfg in one of the lists under [options.extras_require].

Packaging/One command install

You can distribute your code using PyPI. The guide can help you decide which tool to use for packaging.

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, and can thus be installed with pip3 install --editable .[dev]
• Tests can be run with pytest
  • This is configured in setup.cfg
• 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.
• To generate HTML documentation, run make html in the docs/ folder.
• To put the documentation on ReadTheDocs, log in to your ReadTheDocs account, and import the repository (under 'My Projects').
  • Include the link to the documentation in your project's README.md.
• Relevant section in the guide

Coding style conventions and code quality

• Check your code style with prospector
• You may need run pip install --editable .[dev] first, to install the required dependencies
• You can use yapf to fix the readability of your code style and isort to format and group your imports
• Relevant section in the guide

Continuous code quality

• Sonarcloud is used to perform quality analysis and code coverage report on each push
• Sonarcloud must be configured for the analysis to work
  1. go to Sonarcloud
  2. login with your GitHub account
  3. add organization or reuse existing one
  4. set up repository
  5. go to new code definition administration page and select Number of days option
• The analysis will be run by GitHub Action workflow
• To be able to run the analysis, a token must be created at Sonarcloud account and this token must be added as SONAR_TOKEN to secrets on GitHub

Package version number

• We recommend using semantic versioning.
• For convenience, the package version is stored in a single place: notebooks/.bumpversion.cfg. For updating the version number, make sure the dev dependencies are installed and run bumpversion patch, bumpversion minor, or bumpversion major as appropriate.
• Don't forget to update the version number before making a release!

Publish on Python Package Index (PyPI)

To publish your package on PyPI, you need to create a PyPI API token and save it as a secret called PYPI_TOKEN on Settings page

Creating a release on GitHub will trigger a GitHub action workflow to publish the release on PyPI for you.

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