SKA Python Skeleton Project

Documentation Status

Briefly describe your project here

Requirements

The system used for development needs to have Python 3 and pip installed.

Install

Always use a virtual environment. Pipenv is now Python’s officially recommended method and the one used by default in this repo.

Follow these steps at the project root:

First, ensure that ~/.local/bin is in your PATH with:

> echo $PATH

In case ~/.local/bin is not part of your PATH variable, under Linux add it with:

> export PATH=~/.local/bin:$PATH

or the equivalent in your particular OS.

Then proceed to install pipenv and the required environment packages:

> pip install pipenv # if you don't have pipenv already installed on your system
> pipenv install
> pipenv shell

You will now be inside a pipenv shell with your virtual environment ready.

Use exit to exit the pipenv environment.

Testing

  • Put tests into the tests folder

  • Use PyTest as the testing framework

  • Run tests with python setup.py test

    • Configure PyTest in setup.py and setup.cfg

  • Running the test creates the htmlcov folder

    • Inside this folder a rundown of the issues found will be accessible using the index.html file

  • All the tests should pass before merging the code

Code analysis

  • Use Pylint as the code analysis framework

  • By default it uses the PEP8 style guide

  • Use the provided code-analysis.sh script in order to run the code analysis in the module and tests

  • Code analysis should be run by calling pylint ska_python_skeleton. All pertaining options reside under the .pylintrc file.

  • Code analysis should only raise document related warnings (i.e. #FIXME comments) before merging the code

Writing documentation

  • The documentation generator for this project is derived from SKA’s SKA Developer Portal repository

  • The documentation can be edited under ./docs/src

  • If you want to include only your README.md file, create a symbolic link inside the ./docs/src directory if the existing one does not work:

$ cd docs/src
$ ln -s ../../README.md README.md

  • In order to build the documentation for this specific project, execute the following under ./docs:

$ make html

  • The documentation can then be consulted by opening the file ./docs/build/html/index.html