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

Cookiecutter template for Python project supporting Make, Tox, release to Pypi, test on Travis&Appveyor, docs on RTD
https://github.com/andy-maier/cookiecutter-python

cookiecutter-template python

Last synced: 26 days ago
JSON representation

Cookiecutter template for Python project supporting Make, Tox, release to Pypi, test on Travis&Appveyor, docs on RTD

• Host: GitHub
• URL: https://github.com/andy-maier/cookiecutter-python
• Owner: andy-maier
• License: apache-2.0
• Created: 2019-12-30T20:16:45.000Z (almost 5 years ago)
• Default Branch: master
• Last Pushed: 2022-09-02T20:24:11.000Z (about 2 years ago)
• Last Synced: 2023-03-06T04:32:15.194Z (over 1 year ago)
• Topics: cookiecutter-template, python
• Homepage:
• Size: 152 KB
• Stars: 1
• Watchers: 2
• Forks: 0
• Open Issues: 2
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

Awesome Lists containing this project

README

        
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):

    .. code-block:: bash

        $ pip install cookiecutter

2.  In the directory where you want the subdirectory for the new Python project

    to be created, issue:

    .. code-block:: bash

        $ 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:

    .. code-block:: bash

        $ 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:

     .. code-block:: bash

         $ 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:

     .. code-block:: bash

         $ 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:

     .. code-block:: bash

         $ 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 `_.