Repository Configuration¶

This page explains how this template repository is organized by detailing the building blocks of the project skeleton.

Branch organization¶

Two main branches set the development workflow: the master branch and the latest branch. The latest branch is thought to evolve according to continuous integration practices, and is referred as the latest build or version; while, on the other hand, the master branch is considered the stable or production version. Under this configuration the master branch receives updates from the latest build periodically or when a new version/patch is ready for deployment. Read further about Branch workflow.

Project Layout¶

The project layout follows the src, tests, docs and devtools folders layout.

The src layout¶

I have discovered that storing the source library folder under a src directory instead of directly in the project’s root is by far the most controversial point out there on the wild Internet. Here I adopted the src-based layout discussed by ionel in his blog post. When reading through the discussed arguments, I found this strategy to have many advantages over the common root directory layout and no added disadvantage.

In detail, though encapsulating the source in a src directory is an uncommon practice in Python projects, adopting this practice avoids unexpected and uncontrolled code imports that could lead to wrong testing operations, as well stated by ionel, see his src-nosrc example. On the same hand, encapsulating the source under a src directory does not create any additional problems that would be avoided by the standard layout with source directly on a rootdir-based folder, usually named the same as the package name.

tests¶

Tests are nicely encapsulated in a tests folder. With this encapsulation, outside the library folder, it is easier to control that tests do not import from relative paths and can only access the library code after library installation (whatever the installation mode is). Also, having tests in a separated folder facilitates the configuration files layout on excluding tests from deployment (MANIFEST.in) and code quality (.codacy.yaml) or coverage (.coveragerc).

docs¶

All documentation related files are stored in a docs folder. These include files related to the library documentation but also with the development process, such as: AUTHORS, CONTRIBUTING, CHANGELOG, etc.

devtools¶

The devtools folder hosts the files related to development. Here I used the idea explained by Chodera Lab in their structuring your project guidelines, though for other issues described previously, I do not follow their guides, as explained in context.

CI Platforms¶

Here we provide an overview of the implementation strategies for the different continuous integration and quality report platforms. We have adopted a total of seven platforms, two for building and testing, two for code quality control, two for test coverage and one for documentation deployment:

Building and testing
- Travis-CI (Linux and OSX)
- Appveyor (Windows)
Quality Control
- Codacy
- Code Climate
Test Coverage
- Codecov
- Coveralls
Documentation
- Read the Docs

We acknowledge the existence of many other platforms for the same purposes. Though, we have chosen these because they fit the size and scope of the projects to which this template aims at and are those platforms most used within our field of development.

Choosing the CIs¶

Please note that you do not need to use all these platforms when adapting this template for your project, we do suggest you use at least one for each topic. For example, you do not need to activate Appveyor if you do not intent to deploy/distribute your code for Windows machines. Also, for quality control and test coverage one of the two provided options may suffice, however, having both is free and you can benefit from the different analysis reports the platforms provide.

Note

To NOT use a specific CI platform simply do not activate it in their website, remove the configuration file from the root directory of the project, and remove the badge image link from the README.rst file. Continue reading to understand better these concepts.

Activate CI¶

To activate the different CI platforms for you repository just navigate to their website, login with your GitHub account and activate the repository. The configurations provided in this template should to the rest automatically :-), just start pushing your commits to the server.

Travis-CI¶

The configuration for Travis-CI is defined in the .travis.yml file.

Overall, the Travis configuration defines how to execute the different tox environments defined in the tox.ini file.

Find in the .travis.yml file the complete explanation for the implementation proposed, here we mirror the file:

Todo

Configure Travis to run OSX tests.

Appveyor¶

The configuration for AppVeyor-CI is defined in the .appveyor.yml file.

Contrary to our configuration for Travis-CI, with Appveyor, the configuration file simply attempts to build the package and run the unittests battery in the different Python versions.

Find in the .appveyor.yml_ file the complete explanation for the implementation proposed, here we mirror the file:

Codacy¶

There is not much to configure for Codacy in the version we propose in this template. The only setup provided is to exclude the analysis of test scripts, this configuration is provided by the .codacy.yaml file at the root director of the repository. If you wish Codacy to perform quality analysis on your test scripts just remove the file or comment the line. Here we mirror the .codacy.yaml file:

---
exclude_paths:
 - 'tests/**'

Code Climate¶

There is not much to configure for Code Climate in the version we propose in this template. The only setup provided is to exclude the analysis of test scripts and other dev files Code Climate by default analysis, this configuration is provided by the .codeclimate.yml file at the root director of the repository. If you wish Code Climate to perform quality analysis on your test scripts just remove the file or comment the line.

Code Climate provides a technical debt percentage that can be retrieved nicely with a badge<Badges>

Here we mirror the .codeclimate.yml file:

version: "2"         # required to adjust maintainability checks
checks:
  argument-count:
      enable: false
  complex-logic:
    config:
      threshold: 4
  file-lines:
    config:
      threshold: 2000
  method-complexity:
    config:
      threshold: 5
  method-count:
    config:
      threshold: 20
  method-lines:
    config:
      threshold: 25
  nested-control-flow:
    config:
      threshold: 4
  return-statements:
    config:
      threshold: 4
  similar-code:
    config:
      threshold: # language-specific defaults. an override will affect all languages.
  identical-code:
    config:
      threshold: # language-specific defaults. an override will affect all languages.
plugins:
  radon:
    enabled: true
    config:
      threshold: "C"
      python_version: 3
  bandit:
    enabled: true
  sonar-python:
    enabled: true
    config:
      tests_patterns:
        - tests/**
      minimum_critial: major
  editorconfig:
    enabled: false
    config:
      editorconfig: .editorconfig
exclude_patterns:
  - "tests/"
  - ".ci/"
  - "alphas/"

Code coverage¶

Codecov¶

Codecov is used very frequently to report test coverage rates the software under development. Activate your repository under Codecov as done for any other CI platform. Additional configurations:

In general settings change the default branch to the latest branch, if that is your preferred settings.

Coveralls¶

Coveralls is also included in this template skeleton. Again, activate the coveralls profile by linking your repository to the server (same as with other CI platforms).

The configuration to Coveralls, .coveragerc is the same as of Codecov.

Sending coverage reports¶

Coverage reports are sent to both Codecov and Coveralls servers during the Travis-tox -cover environment. .travis.yml configuration handles this and you do not need to worry about nothing else.

The options specific to Codecov report (actually coverage package) are described in .coveragerc file, mirrored bellow, description of the configuration file is provided as comments.

[paths]
source =
    src
    */site-packages

[run]
branch = true
source =
    sampleproject
parallel = true

[report]
show_missing = true
precision = 2
omit = *migrations*
exclude_lines = 
    if __name__ == .__main__.:

The .coveragerc can be expanded to further restraint coverage analysis, for example adding these lines to the exclude tag:

[report]
exclude_lines =
    if self.debug:
    pragma: no cover
    raise NotImplementedError
    if __name__ == .__main__.:

Read the Docs¶

Activate your project at Read the Docs platform (RdD), their web interface is easy enough to follow without further explanations. If your documentation is building under the tox workflow it will build in at Read the Docs.

Docs Requirements¶

Requirements to build the documentation page are listed in docs/requirements.txt:

sphinx>=2.2
sphinx-py3doc-enhanced-theme
sphinx-argparse
CommonMark
mock

In this repository we are using Sphinx as documentation builder and the sphinx-py3doc-enhanced-theme as theme, though you can use many different theme flavors, see Sphinx Themes.

Build version¶

By default, RdD has two main documentation versions (also called builds): the latest and the stable. The latest points to the master branch while the stable points to the latest GitHub tag. Therefore, every time changes are pushed to the master branch a new build in the latest version of the documentation is created, while the stable version is built only when new tags are created.

However, for many projects it is desirable a different setup where the master branch holds the stable version, that is, the code referent to the latest tag, while another branch (usually named latest or develop) set to the repositories’ default, holds the latest development code that has not yet been merged to the master and considered stable. This is the setup of this template repository. Under this setup, it is desirable that the documentation build referent to the latest version points to the latest branch, the stable doc build will always point to the latest tag. This can be edited in Admin -> Advanced Settings and Default version and Default branch.

Google Analytics¶

Read the Docs allows straight forward implementation of Google Analytics tracking in the project documentation, just follow their instructions.

Badges¶

Badges point to the current status of the different Continuous Integration tools, for example, Travis-CI or Appveyor, but also documentation and code quality reports.

This project has two badge groups, one for the master (stable) branch and other for the latest (develop) branch. By showing information for these two groups the development team can keep track on the improvements (or losses) on code quality or the success of the different building processes.

Each platform provide their own badges, yet you can further tune the badges style by creating your own personalized badge with Shields.io.

You will notice that the badge for Code Climate is missing in the master branch. I could not find yet a straightforward and easy implementation for several branches at Code Climate, so, the badge reports on the main branch set for the repository, in this case the latest branch. Also at Shields.io there is no shortcut to branch for this platform as there is for others.

I observed this same issue for COVERALLS, but then I realize that after the first commit to the master, COVERALLS actually displays nicely the information for both branches.

Repository Configuration¶

Branch organization¶

Project Layout¶

The src layout¶

tests¶

docs¶

devtools¶

CI Platforms¶

Choosing the CIs¶

Activate CI¶

Travis-CI¶

Appveyor¶

Codacy¶

Code Climate¶

Code coverage¶

Codecov¶

Coveralls¶

Sending coverage reports¶

Read the Docs¶

Docs Requirements¶

Build version¶

Google Analytics¶

Badges¶

Table Of Contents

This Page

Navigation

Repository Configuration¶

Branch organization¶

Project Layout¶

The src layout¶

tests¶

docs¶

devtools¶

CI Platforms¶

Choosing the CIs¶

Activate CI¶

Travis-CI¶

Appveyor¶

Codacy¶

Code Climate¶

Code coverage¶

Codecov¶

Coveralls¶

Sending coverage reports¶

Read the Docs¶

Docs Requirements¶

Build version¶

Google Analytics¶

Badges¶

Navigation