Skip to content

Latest commit

 

History

History
74 lines (50 loc) · 2.93 KB

README.md

File metadata and controls

74 lines (50 loc) · 2.93 KB
Raw

NEASQC lib template

This repository is a template for NEASQC libraries.

Licence

The LICENCE file contains the default licence statement as specified in the proposal and partner agreement.

Building and installing

For simplicity, an example of setup.py file is provided in this template. Feel free to modify it if you have exotic build recipes.

Coding conventions

In order to simplify the coding conventions, we provide a pylint.rc file in misc/pylint.rc. This will allow you to easily check your naming conventions and various other aspects. This is not a strict guidline, as pylint can be quite pedantic sometimes (but also very helpful).

A few remarks:

  • pylint can be integrated in most editors (and we strongly advise you to)
  • running pylint on several source files in one go can find errors such as circular imports or code duplication:
python -m pylint --rcfile=./misc/pylint.rc <my_source_dir>

or

pylint --rcfile=./misc/pylint.rc <my_source_dir>

depending on how you installed pylint.

Testing and continuous integration

In order to uniformise the continuous integration process across libraries, we will assume that:

  • all the tests related to your library are compatible with pytest
  • there exists a 'test' recipe in the setup.py file

The default test recipe (in this template) simply calls pytest on the full repository. Pytest detects:

  • any file that starts with test_ (e.g test_my_class.py)
  • inside these files, any function that starts test_
  • any class that starts with Test

You can run it with:

python setup.py test

This way, you can write tests either right next to the corresponding code (convenient) or in a tests folder at the root of the repository.

If you are not familiar with unit testing and you feel that it's too much for your project, that's fine. The bare minimum would be to include some run examples wrapped in test functions (functional tests).

Remark that in this template, the same tests are in my_lib/test_my_lib.py and tests/test_my_lib.py.

GitHub CI

This repository contains a GitHub Workflow file that will automatically run pytest when changes are pushed.
Details on disabling and enabling this feature can be found here.

Documentation

Customize the GitHub Workflow YAML file: repo_name/.github/workflow/sphinx_doc.yml There is a basic index.rst template under 'doc'. Modify it as you want.

Any modification under the folder 'doc' pushed to GitHub will trigger a rebuild of the documentation (using GitHub CI). If the build is successful, then the resulting html documentation can be access at: https://neasqc.github.io/repo_name

Notes:

  • You can follow the build process on the 'Actions' tab below the name of the repository.
  • neasqc.github.io does not immediately update. You may need to wait a minute or two before it see the changes.