snickerdoodle 0.2.0

Easy-to-use, general-purpose, modern cookiecutter template for Python

snickerdoodle

Version
Status
Documentation
Compatibility
Stats

What is snickerdoodle?

snickerdoodle is an easy-to-use, general-purpose cookiecutter template for Python projects utilizing modern tools and best practices. To see an example repository using this template, check out snickerdoodle_demo.

Why use snickerdoodle?

There are a lot of cookiecutter templates. However, many are difficult to use, overly opinionated, or underdocumented. I created snickerdoodle because I couldn't find another cookiecutter template meeting these criteria:

• Modern: follows best practices, using modern, actively developed tools.
• Batteries Included: allows you to start coding immediately.
• Flexible: no required usage of any external services. (SonarCloud, Travis, CircleCI, Tox, etc.).
• Low-Maintenance: every commit automatically deploys the documentation as well as lints, formats, and tests the repository.
• Well-Documented: the documentation includes complete guides for new and advanced users.
• PEP-Compliant: all included tools follow accepted PEPs (unfortunately, that ruled out using poetry, which is still not PEP 621 or PEP 631 compliant, three years after they were accepted, resulting in compatibility problems because of its non-standard pyproject.toml format).

Tools

To accomplish those goals, snickerdoodle includes modern, stable tools for package construction and management that do not require any external services or costs:

• Dependency Management: and
• Documentation: with the theme on
• Testing:
• CI/CD:
• Code Style: , , and
• Templating:

Options

In addition to the included tools above, snickerdoodle includes several options in the cookiecutter questionnaire that can be automatically applied as part of the templating process:

• Badge Style: , , , , or
• Push an Initial Commit to GitHub
• Build and Deploy Basic Documentation to GitHub Pages
• Create a Virtual Environment in the Repository's ".venv" Folder

Getting started

Setup

If you are new to cookiecutter or simply want to guarantee that the created repository works as intended, follow the instructions in the snickerdoodle tutorial.

If you are familiar with cookiecutter templates, you can go about the normal construction process. However, if you do not select the optional automatic setup features in the questionnaire, you should follow the instructions for manually setting up your virtual environment and deploying your documentation in the snickerdoodle tutorial. It is especially important to follow the document deployment process for your initial deployment - after that GitHub Actions will automatically update and redeploy the documentation (and you need not use the manual process again).

Usage

After your repository is created, you can start coding right away. Every push to GitHub will run any tests in the "tests" folder, deploy documentation to GitHub Pages, and apply ruff for linting and formatting. For more information about the following topics, just click on the corresponding hyperlink.

• Formatting and Linting
• GitHub Actions
• Publishing
• Repository Layout
• Versioning

Contributing

Contributors are always welcome and should find snickerdoodle easy to work with. The template is highly documented so that users and developers can adapt or extend snickerdoodle to work with their projects. So, forking and creating different template spins is encouraged. If you want to contribute directly, feel free to grab an issue to work on or make a suggested improvement. If you wish to contribute, please read the Contribution Guide and Code of Conduct.

Similar Projects

These are other cookiecutter templates using pdm as their dependency manager:

• cookiecutter-docker-python-pdm: uses Docker and black.
• cookie: uses mkdocs and GitHub Actions, but also adds conda, nox, black, and pyright.

And, these are other general-purpose cookiecutter templates that are well-maintained, modern, and well-documented:

• cookiecutter-hypermodern-python: uses, among other tools, sphinx, GitHub Actions, nox, mypy, flake8, and poetry. If you do not mind those choices and wanted a modern, maintained template, this is the one to use.
• cookiecutter-pylibrary: a newer template that is minimal compared to most and uses, among other tools, sphinx, GitHub Actions, setuptools, Tox, and Travis-CI.
• wolt python package cookiecutter: an interesting template that uses cruft instead of base cookiecutter. The created repository uses, among other tools, mkdocs, GitHub Actions, black, flake8, and poetry.

If you are interested in going beyond cookiecutter (or its forks), copier is a powerful, newer templating package and there is a great template that incorporates several of the tools used in snickerdoodle:

• copier-pdm: includes, among other tools, pdm, mkdocs, and ruff.

Acknowledgements

I'd also like to extend a special thanks to pawamoy whose excellent pdm and mkdocs extensions and utlities are incorporated into snickerdoodle. Some of the scripts, documentation, configuration files, and other CI code were all adapted from pawamoy's repositories.

I would also like to thank the University of Kansas School of Law for tolerating and supporting this law professor's coding efforts, an endeavor which is well outside the typical scholarly activities in the discipline.

License