Documentation

[vhirtham]

GitHub Actions (CI)

Informations

• GitHub Actions run multiple project-related tasks on cloud servers. It can be used as CI service amongst other things.
• Each run: of a job: forgets all previously set environmental variables
• Syntax for .yml files
• Preinstalled software on servers
• Virtual environments (Docker)
• Setup CI
• Conda in GitHub actions Issue

Badge

• See badge section of thislink
• One possibility: https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_NAME>/badge.svg
• White spaces in the <WORKFLOW_NAME> must be replaced by %20

Installation

• Add a .github/workflows directory to the projects root directory
• Create a .yml for each individual workflow
• Edit the .yml. Example:

name: CI Windows
on: [push]

jobs:
  test:
    name: CI Build
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [windows-latest]
    steps:
    - uses: actions/checkout@v1
    - name: Add conda directories to PATH
      run: |
        echo ::add-path::C:\Miniconda
        echo ::add-path::C:\Miniconda\Scripts
    - name: Print conda info
      run: conda info -a
    - name: Create conda environment
      run: conda create -yy -q -n test-environment python=3.7 pytest
    - name: Init bash
      run: conda init powershell
    - name: Run tests
      run: |
        conda activate test-environment
        pytest

Travis CI

Informations

• Travis is a Linux based CI service. Hence one can use the Linux package manager sudo apt-get install etc.
• Travis Documentation
• Conda on Travis

Badge

• Go to the Projects Travis site and click on the badge
• Copy the link and add it to the README.md

Installation

• Activate Travis CI via GitHub and Travis homepages (Travis homepage)
• Create .travis.yml in the project root directory
• Modify the .travis.yml as needed. Example:

language: python
python:
  - "3.7"      # current default Python on Travis CI

install:
  - sudo apt-get update
  # We do this conditionally because it saves us some downloading if the
  # version is the same.
  - if [[ "$TRAVIS_PYTHON_VERSION" == "2.7" ]]; then
      wget https://repo.continuum.io/miniconda/Miniconda2-latest-Linux-x86_64.sh -O miniconda.sh;
    else
      wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh;
    fi
  - bash miniconda.sh -b -p $HOME/miniconda
  - source "$HOME/miniconda/etc/profile.d/conda.sh"
  - hash -r
  - conda config --set always_yes yes --set changeps1 no
  - conda update -q conda
  - conda info -a

  - conda create -q -n test-environment python=$TRAVIS_PYTHON_VERSION pytest pytest-cov codecov
  - conda activate test-environment

script:
  - pytest --cov-report term --cov=MyPackages

after_success:
  - codecov

Appveyor CI

Informations

• Appveyor is a Windows-based CI service.
• Appveyor Documentation
• Useful link
• Miniconda and python are already installed - see link above

Badge

• Go to the Projects Appveyor site
• Go to the settings menu
• Click on the Badges tab
• Copy the link and add it to the README.md

Installation

• Activate Appveyor CI via GitHub and appvayor homepages (Travis homepage)
• Create .appveyor.yml in the project root directory
• Modify the .appveyor.yml as needed. Example:

environment:
  matrix:
    - PYTHON_VERSION: 3.6
      MINICONDA: "C:\\Miniconda36"



install:
  - "set path=%path%;%MINICONDA%;%MINICONDA%\\Scripts;"
  - conda config --set always_yes yes --set changeps1 no
  - conda info -a
  - "conda create -q -n test-environment python=%PYTHON_VERSION% pytest"
  - activate test-environment

build: false

test_script:
  - pytest

Coverage / Codecov

Informations

• Codecov documentation
• Codecov is a web-service to check how many lines of code are tested in your project
• Coverage reports must be generated and uploaded manually or by a CI service (the common approach)
• pytest-cov documentation

Badge

• Go to the Projects Codecov site
• Go to the settings menu
• Click on the Badges tab
• Copy the link and add it to the README.md

Installation

• Activate codecov via GitHub and codecov homepages (Codecov homepage)
• Add to .travis.yml:

install:
  - conda install pytest-cov
  - conda install codecov

script:
  - pytest --cov-report term --cov=$directory$

after_success:
  - codecov

• To configure when a coverage report should be considered as a failure (on GitHub) and which files should be ignored, add a .codecov.yml to the project root directory
• Modify .appveyor.yml as needed. Example:

codecov:
    branch: master
    notify:
        require_ci_to_pass: yes

coverage:
    precision: 2
    round: down
    range: "70...100"

    status:
        project:
            default:
                enabled: yes
                target: 85%
                threshold: 5%


        patch:
            default:
                enabled: yes
                target: 85%

ignore:
    - "tests"
    - "*__init__.py"

Typo CI

Information

• A tool to check for typos in the code of pull requests
• Leaves a comment in the pull request
• Documentation

Installation

• Activate App on GitHub
• Optionally add .typo-ci.yml and configure it (see documentation)

Pep8Speaks

Information

• Checks pull request for coding style violations
• Uses pycodestyle or flake8 as linter
• Leaves a comment in the pull request if an error is found
• Documentation
• Write a comment with @pep8speaks suggest diff to get a gist with suggested fixes
• Write a comment with @pep8speaks pep8ify to get an automatically generated pull request against the current branch that fixes most of the PEP8 errors

Installation

• Activate the App on GitHub
• Optionally add a .pep8speaks.yml and configure it
• Optionally add an entry for pycodestyle or flake8 in setup.cfg to configure them

[vhirtham]

Documentation with Sphinx

Autosummary

General

• Generates the API documentation automatically by evaluation of the doc strings in each python file (Documentation)
• The conf.py needs the following lines:

extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosummary'
]
autosummary_generate = True

Remember this quote from Stackoverflow:

In each package, the init.py file can have .. automodule:: package.module components for each part of the package.

Then you can .. automodule:: package and it mostly does what you want.

Templates

• There is no inherent recursion. The autosummary file of a module will not generate documentation pages for each function. To overcome this, templates can be used.
• Use the :template: key to select the template you want to use
• Stackoverflow link with some templates
• Example:

someFile.rst:

API Documentation
=================

.. currentmodule:: MyPackages

.. autosummary::
   :template: autosummary/modules.rst
   :toctree: _autosummary

   MyFuncs

_templates/autosummary/modules.rst:

{{ fullname | escape | underline }}

.. rubric:: Description

.. automodule:: {{ fullname }}

.. currentmodule:: {{ fullname }}

{% if classes %}
.. rubric:: Classes

.. autosummary::
    :toctree: .
    {% for class in classes %}
    {{ class }}
    {% endfor %}

{% endif %}

{% if functions %}
.. rubric:: Functions

.. autosummary::
    :toctree: .
    {% for function in functions %}
    {{ function }}
    {% endfor %}

{% endif %}

Pitfalls

Doc-Strings

Doc-Strings need a clear line between description and parameters to be translated correctly. This

"""
Description
:param a: bla bla
"""

will produce Description:param a: bla bla as a description. The parameter a won't be documented at all. So add a blank line between the description and the parameter documentation:

"""
Description

:param a: bla bla
"""

Clean up

make clean html does not delete automatically generated .rst files by autosummary. So some indirect changes (for example on the template) might not be considered during the next build. Delete them manually to be sure.

Keep in mind:

Git warning when adding Makefile in docs directory:

warning: LF will be replaced by CRLF in docs/Makefile.
The file will have its original line endings in your working directory

Check Stackoverflow