Skip to content

Latest commit

 

History

History
155 lines (109 loc) · 5.62 KB

README.rst

File metadata and controls

155 lines (109 loc) · 5.62 KB
Raw

Cookiecutter template for Python projects

This is a template for the popular cookiecutter project for generating a Python project.

The generated Python project features the following:

  • Use of GitHub (github.com) as a repository. This only affects links generated in the documentation and readme files and can easily be adjusted by you to something else after creating the project.
  • Use of GNU Make for encapsulating the typical actions such as install, test, etc. Each invocation of make operates in the currently active Python environment that has previously been activated by the user.
  • Use of Tox for running make for checking and testing in a number of virtual Python environments created by Tox.
  • Use of GitHub Actions as a CI system on Linux, MacOS, Windows.
  • Use of Sphinx for generating documentation for the Python package, that is ready to be published on ReadTheDocs.
  • Use of coveralls for reporting and comparing test coverage.
  • Selection of the license to be used for the new project.

Usage

  1. If you don't have cookiecutter installed, install it (e.g. into your system Python):

    $ pip install cookiecutter

  2. In the directory where you want the subdirectory for the new Python project to be created, issue:

    $ cookiecutter https://github.com/andy-maier/cookiecutter-python

    You will be prompted for the following input parameters:

    • project_name - A project name for use in titles, docs, etc. May contain blanks and mixed case.
    • short_description - A short (one-line) description of the project.
    • package_name - The name of the package on PyPI and of the Python package to import. Should be lower case with no other special characters than underscores.
    • package_version - Initial package version in M.N.P syntax (the project uses semantic versioning).
    • github_org - Name of the GitHub organization that contains the project repo.
    • github_repo - Name of the GitHub repository within the GitHub organization.
    • full_name - Full name of the author. Will be used as author and maintainer in setup.py.
    • email - Email address of the author. Will be used as author and maintainer email in setup.py.
    • command_line_interface - Selection of command line packages that you want to use.
    • open_source_license - Selection of license that you want to use.
    • install_test - Choose whether to include ability for install testing.
    • end2end_test - Choose whether to include ability for end2end testing.

    This creates the new project in a subdirectory named new_{github_repo}.

    To see which targets the Makefile supports, issue in the new directory:

    $ make help

  3. To put that project on GitHub, the following steps represent a proven practice. You may choose to do that differently, though.

    The {x} notation is used to refer to the value of cookiecutter input parameter x.

    • On GitHub (https://github.com), create a new repository {github_org}/{github_repo}.

    • On GitHub, change the settings of the new repo:

      • In Options:
        • Disallow merge commits.
        • Automatically delete head branches.

    • Clone that repo to your workstation and go to its working directory:

      $ git clone [email protected]:{github_org}/{github_repo}.git
$ cd {github_repo}

    • Set user name and email in your local config of the cloned repo:

      $ git config --local --add user.name "{full_name}"
$ git config --local --add user.email {email}

    • Add, commit and push the generated cookiecutter project to the repo, creating a master branch:

      $ git checkout -b master
$ mv ../new_{github_repo}/* .
$ git add --all
$ git commit -sm "Initial project as generated by cookiecutter"
$ git push --set-upstream origin master

    • On GitHub, go to Settings / Branches and add a branch protection rule for branch "master".

    • Testing with GitHub Actions is automatically enabled since a workflow file .github/workflows/test.yml has been created.

  4. To enable coverage reporting to Coveralls:

    • Have a user on Coveralls (https://coveralls.io), have it authorized for your GitHub account, and log in to Coveralls.
    • In the left hand menu, add a repo and turn the new GitHub repo on.

  5. To enable publishing the documentation to ReadTheDocs:

    • Have a user on ReadTheDocs (https://readthedocs.org), and log in to ReadTheDocs.

    • Go to "My Projects", select "Import a project", sync to get the repo list updated, and select the new repo.

      Attention: On the "Project Details" page, change the name of the ReadTheDocs project from its default to become {package_name}.

      Since project names are global on ReadTheDocs, you may need to adjust that name to find an unused name. If you end up with a name other than {package_name}, you need to update the ReadTheDocs links in the following files in the new repo:

      • README.rst
      • docs/development.rst

  6. To enable publishing the package on PyPI:

    • Have or create a user on PyPI (https://pypi.python.org). The project on PyPI is created when the first version of the package is uploaded.

License

This cookiecutter template is provided under the Apache 2.0 license.