Welcome to cookietemple’s documentation!
A cookiecutter based project template creation tool supporting several domains and languages with advanced linting, syncing and standardized workflows to get your project kickstarted in no time.
Documentation: https://cookietemple.readthedocs.io .
cookietemple overview
Installing
Start your journey with cookietemple by installing it via $ pip install cookietemple.
See Installation.
config
Configure cookietemple to get started.
list
List all available cookietemple templates.
info
Get detailed information on a cookietemple template.
create
Kickstart your customized project with one of cookietemple’s templates in no time.
See Create a project.
lint
Use advanced linting to ensure your project always adheres to cookietemple’s standards.
bump-version
Bump your project version with many configurable options.
sync
Sync your project with the latest cookietemple release to get the latest template features.
See Syncing a project.
warp
Create a self contained executable. Currently, cookietemple does not ship any templates anymore, where this may be required.
See Warping a project.
upgrade
Check whether you are using the latest cookietemple version and update automatically to benefit from the latest features.
See https://cookietemple.readthedocs.io/en/latest/upgrade.html.
Contributing
cookietemple is a huge open-source effort and highly welcomes all contributions! Join our Discord Channel. Please read contributing to find out how you can contribute.
Installation
Stable release
To install cookietemple, run this command in your terminal:
$ pip install cookietemple
This is the preferred method to install cookietemple, as it will always install the most recent stable release.
If you don’t have pip installed, this Python installation guide can guide you through the process.
From sources
The sources for cookietemple can be downloaded from the Github repo.
You can either clone the public repository:
$ git clone git://github.com/cookiejar/cookietemple
Or download the tarball:
$ curl -OJL https://github.com/cookiejar/cookietemple/tarball/master
Once you have a copy of the source, you can install it with:
$ pip install .
Alternatively you can also install it using the Makefile:
$ make install
Windows Installation
Cookietemple exceeds the standard windows path length limit of 260 characters. In order to correctly install cookietemple the registry has to be adapted. To open the registry editor run:
$ regedit
in your command prompt or directly open it through windows search bar.
Consider backing up your current registry state as changes in the registry can always cause problems resulting in your OS not running correctly. You can either export the complete registry by selecting File > Export … and setting the Export Range flag to ‘All’ or choose to export only selected branches.
Next find the key ‘LongPathsEnabled’ under
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem
and change its ‘Value Data’ from ‘0’ to ‘1’.
Click ‘OK’ and close regedit. Continue installing cookietemple.
Create a project
Creating projects from templates is the heart of cookietemple. Our templates adhere to best practices and try to be as modern as possible. Furthermore, they try to automate tasks such as automatical dependency resolvement and installation, packaging, deployment and more. To learn more about our templates please visit Available templates and check out your template of interest.
Usage
The creation of a new project can be invoked by
$ cookietemple create
which will guide you through the creation process of your (customized) project via prompts. If you do not have cookietemple configured yet, you will be asked to do so. For more details please visit Configure cookietemple.
The prompts follow the pattern of domain (e.g. cli, gui, …), subdomain (if applicable, e.g. website), language (e.g. Python) followed by template specific prompts (e.g. testing frameworks, …). The project will be created at the current working directory, where cookietemple has been called.
After the project has been created, linting (see Linting your project) is automatically performed to verify that the template creation process was successful.
Finally, you will be asked whether you want to automatically push your new project to Github. Note that for this purpose you need to have cookietemple configured with a Github personal access token. For more details about the Github support please visit Github Support.
Flags
--domain: To directly create a template of the the corresponding domain.--path[CWD]: An absolute or relative path to create the template at.All further prompts will still be asked for. Example:
cli. It is also possible to directly create a specific template using its handle
Getting information about available templates
Although, information on all cookietemple templates is provided in Available templates in our documentation, it is often times more convenient to get a quick overview from the commandline.
Hence, cookietemple provides two commands list and info, which print information on all available templates with different levels of detail.
list
cookietemple list is restricted to the short descriptions of the templates. If you want to read more about a specific (sets of) template, please use the info command.
Example output of cookietemple list. Note that the content of the output is of course subject to change.
Usage
cookietemple list can be invoked via
$ cookietemple list
info
The info command should be used when the short description of a template is not sufficient and a more detailed description of a specific template is required.
Example output of cookietemple info.
Usage
Invoke cookietemple info via
$ cookietemple info <HANDLE/LANGUAGE/DOMAIN>
HANDLE: a cookietemple template handle such ascli-python.DOMAIN: a domain for which cookietemple provides templates for. Example:cli.LANGUAGE: A programming language for which cookietemple provides templates for. Example:python.
Linting your project
Linting is the process of statically analyzing code to find code style violations and to detect errors. cookietemple implements a custom linting system, but depending on the template external tools linting tools may additionally be called.
cookietemple’s linting is divided into three distinct phases.
All linting functions, which all templates share are called and the results are collected.
Template specific linting functions are invoked and the results are appended to the results of phase 1
The linting results of the first two phases are assigned into 3 groups:
Passed
Passed with warning
Failed
If any of the checks failed linting stops and returns an error code.
Linting applied to a newly created cli-java project.
To examine the reason for a failed linting test please follow the URL. All reasons are explained in the section Linting codes.
Usage
cookietemple lint can be invoked on an existing project using
$ cookietemple lint <PATH>
PATH[CWD]: The relative path to the project directory.
Flags
Linting codes
The following error numbers correspond to errors found during linting. If you are not sure why a specific linting error has occured you may find more information using the respective error code.
General
general-1
general-2
general-3
COOKIETEMPLE TODO: or TODO COOKIETEMPLE: strings in the respective files. Usually, they point to things that should be
manually configured or require other attention. You may remove them if there is no task for you to be solved.general-4
{{ *cookiecutter* }} statements
should definitely not be present anymore.general-5
cookietemple bump-version.general-6
changelog.rst invalid. The changelog.rst file requires that every changelog section has a header with the version and the corresponding release date.
The version above another changelog section should always be greater than the section below (e.g. 1.1.0 above 1.0.0).
Every section must have the headings **Added**, **Fixed**, **Dependencies** and **Deprecated**.general-7
cookietemple.cfg linting failed. The cookietemple.cfg plays a major role in cookietemple’s sync and bump-version functionality.The linter ensures that following requirements are met:
1.) Every config file should have at least the following sections: bumpversion, bumpversion_files_whitelisted, bumpversion_files_blacklisted, sync_files_blacklisted, sync_level
2.) bumpversion should only contain a current_version value (the project’s current version)
3.) bumpversion_files_whitelisted should contain at least the .cookietemple.yml file in the dot_cookietemple variable
4.) sync_level should only contain a ct_sync_level value (and this value should be one of either patch, minor or major)
5.) sync_files_blacklisted should contain at least the CHANGELOG.rst file (excluding it from syncing to avoid PR updates)
6.) sync should only contain a sync_enabled value (and this value should be one of either True|true|Yes|yes|Y|y|False|false|No|no|N|n)
cli-python
cli-python-1
cli-python-2
cli-python-3
cookietemple.cfg section called sync_files_blacklisted misses either requirements = requirements.txt, requirements_dev = requirements_dev.txt or
changelog = CHANGELOG.rst.
All are required to exclude them from syncing and interference with services like dependabot.cli-java
cli-java-1
cli-java-2
cookietemple.cfg section called sync_files_blacklisted misses build_gradle = gradle.build or
changelog = CHANGELOG.rst.
Both are required to exclude the gradle build file from syncing.lib-cpp
lib-cpp-1
lib-cpp-2
cookietemple.cfg section called sync_files_blacklisted misses changelog = CHANGELOG.rst.
This is required to be excluded from syncing.web-python
web-python-1
web-python-2
cookietemple.cfg section called sync_files_blacklisted misses either requirements = requirements.txt, requirements_dev = requirements_dev.txt
or changelog = CHANGELOG.rst.
All are required to exclude them from syncing and interference with services like dependabot.gui-java
gui-java-1
gui-java-2
cookietemple.cfg section called sync_files_blacklisted misses pom = pom.xml or changelog = CHANGELOG.rst.
Both are required to be excluded from syncing.pub-thesis
pub-thesis-1
pub-thesis-2
cookietemple.cfg section called sync_files_blacklisted misses changelog = CHANGELOG.rst.
This is required to be excluded from syncing.Bumping the version of an existing project
Increasing the version of an already existing project is often times a cumbersome and error prone process, since the version has to be changed in multiple places.
To facilitate this process, cookietemple provides a bump-version command, which conveniently increases the version across several files and commits them.
Additionally, bump-version inserts a new section into the changelog using the specified new version.
New Version (Date)
------------------
**Added**
**Fixed**
**Dependencies**
**Deprecated**
bump-version will verify that your new version adheres to semantic versioning and that you are not trying to update it unreasonably. It is for example not allowed to bump from 2.0.0 to 7.1.2, since in a normal development workflow only 2.0.1, 2.1.0 or 3.0.0 adhere to consecutive semantic versioning. Note that SNAPSHOT versions are allowed! However, it must still follow semantic versioning. Version 1.2.5 therefore cannot be the predecessor of 1.2.5-SNAPSHOT, but only 1.2.4.
Usage
The bump-version command follows the syntax
$ cookietemple bump-version <OPTIONS> X.X.X <PATH>
X.X.X: The new version, where theXcorrespond to integers adhering to consecutive semantic versioning. You may append-SNAPSHOT.PATH[CWD]: The path to thecookietemple.cfgfile, which contains all locations, where the version should be increased.
bump-version applied to a fresh cli-python project
Note that you can use bump-version without passing any parameters. This way, cookietemple will let you choose from three valid options
to bump your projects version. Note that this will only work in the main directory of your project due to some cli constraints.
Flags
--downgrade: To downgrade a version.The changelog won’t be modified. Only use this option as a last resort if something went horribly wrong in your development process. In a normal development workflow, this should never be necessary.
--project-version: To get the current project version.No version bumping will be triggered. Using this flag will cancel any commands executed after and exits the program.
--tagor-t: To tag the bump version commit.One can use this flag to tag the current bump version commit with the updated version for reuse in releases. Note that this will require to be pushed from local to remote by using
git push origin <tagname>.
Configuration
All templates of cookietemple ship with a cookietemple.cfg file, which defines all files bump-version examines.
The bump-version configuration begins with the section:
[bumpversion]
current_version = 0.1.0
where the current version is defined. All files are either white- or blacklisted (see below for explanations).
An arbitrary name is followed by the path to the file: arbitrary_name = path_to_file.
Whitelisted files are listed below a [bumpversion_files_whitelisted] section, e.g.:
[bumpversion_files_whitelisted]
dot_cookietemple = .cookietemple.yml
conf_py = docs/conf.py
All files, which are whitelisted are searched for patterns matching X.X.X, which are updated to the specified new versions.
Any lines, which contain the string <<COOKIETEMPLE_NO_BUMP>> will be ignored.
If files, like Maven pom.xml files, contain many version patterns matching X.X.X, it may be a better idea to blacklist them (section [bumpversion_files_blacklisted]) and enable only specific lines to be updated:
[bumpversion_files_blacklisted]
pom = pom.xml
Analogously to whitelisted files, which allow for specific lines to be ignored, blacklisted files allow for specific lines to be forcibly updated using the string <<COOKIETEMPLE_FORCE_BUMP>>.
Note that those tags must be on the same line as the version (commonly placed in a comment), otherwise they wont work!
Syncing your project
Syncing is supposed to integrate any changes to the cookietemple templates back into your already existing project.
When cookietemple sync is invoked, cookietemple checks whether a new version of the corresponding template for the current project is available.
If so, cookietemple creates a temporary project with the most recent template and pushes it to the TEMPLATE branch.
Next, a pull request is submitted to the development branch.
Please note that the required CT_SYNC_TOKEN (see below) is automatically set and manual syncing should be avoided if possible.
The syncing process is configurable by setting the desired lower syncing boundary level and blacklisting files from syncing (see Enable/Disable sync).
Requirements for sync
For syncing to work properly, your project has to satisfy a few things:
A Github repository with your projects code (private or public, organization or non-organization repository).
An unmodified
.cookietemple.ymlfile. If you modify this file, which you should never do, syncing may not be able to recreate the project with the most recent template.An active repository secret called
CT_SYNC_TOKENfor your project’s repository containing the encrypted personal access token with at leastreposcope.A running, unmodified workflow called
sync_project.yml. Modifying this workflow should never be done and results in undefined sync behaviour.
Points 3 and 4 are only required when not syncing manually.
Usage
To sync your project manually, simply run
$ cookietemple sync [PROJECT_DIR] [PAT] [GITHUB_USERNAME]
PROJECT_DIR[CWD] : The path to thecookietemple.cfgfile.PAT[Configured pat] : A Github personal access token with at least thereposcope. Thesync_project.ymlGithub workflow uses the PAT set as a Github secret.GITHUB_USERNAME[Configured username] : The Github username to submit a pull request from. The supplied PAT has to be associated with this username.
Flags
--set-token: UpdateCT_SYNC_SECRETof your project’s repo to a new PAT. Note that the Github username and the PAT must still match for automatic syncing to work.check-update: Check, whether a new release of a template for an already existing project is available.
Configuring sync
Enable/Disable sync
Cookietemple aims to provide the user as much configuration as possible. So, the sync feature is optional and should also
be switched on or off. If you want to enable sync (which is the default), the sync_enable accepts the following values: True, true, Yes, yes, Y, y. To disable sync,
simply change this value into one of False, false, No, no, N, n. It can be configured in the:
[sync]
sync_enable = True
section.
Sync level
Since cookietemple strongly adheres to semantic versioning our templates do too. Hence, it is customizable whether only major, minor or patch releases of the template should trigger cookietemple sync. The sync level therefore specifies a lower boundary. It can be configured in the:
[sync_level]
ct_sync_level = minor
section.
Blacklisting files
Although, cookietemple only submits pull requests for files, which are part of the template, sometimes even those files should be ignored.
Examples could be any html files, which, at some point, contain only custom content and should not be synced.
When syncing, cookietemple examines the cookietemple.cfg file and ignores any file patterns (globs) (e.g. *.html) below the [sync_files_blacklisted] section.
IMPORTANT NOTE: If you would like to add some files to this section, make sure your current branch (if you are syncing manually, which is not recommended) or your default branch
has the latest blacklisted sync file section with your changes, so it will be used by the sync.
Packaging using warp
cookietemple ships with Rust binaries of Warp for the three major operating systems, Linux, MacOS and Windows.
Warp can be called when complex output scripts with dependencies should be merged into single, distributable binaries.
An example would be the output of jlink applied to modular Java projects.
However, warp can also be applied to .NET Core projects, NodeJS and others, making it more flexible than e.g. the with Java 14 introduced JPackager.
Example output of cookietemple warp applied to a (former) gui-java project. The project was first packaged using mvn javafx:jlink and then warp was applied. Please note the relative path for --exec. Note that this is not necessary for GraalVM based projects.
The resulting binary is self contained and does not have any additional dependencies. Note however, that the binaries are not cross platform. You need to compile and package on the target platform. For more information please read the Warp README. Currently no cookietemple template requires Warp.
Warp setup
Warp for all major platforms (Linux, Windows 10+, MacOS) is already shipped with cookietemple. Hence, there is no need to install the Warp externally. However, the first time that you invoke Warp you may be asked for your sudo/administrator password, since the Warp executable needs to be granted executable rights. You should only be prompted once, since this setting is permanent. If you update cookietemple or reinstall, the Warp executable may be replaced and you once again need to provide it the required rights.
Usage
Invoke warp by running
$ cookietemple warp --input_dir <INPUTDIR> --exec <EXECUTABLE> --output <OUTPUT>
Flags
input-dir: The path to the directory to package.--exec: A relative path from the packaged folder to the executable. Please note that the--execoperates relative to the packaged folder and may result in ‘file not found’ errors, if a wrongly relative path is given!--output: A path to the output directory.
Available templates
cookietemple currently has the following templates available:
In the following every template is devoted its own section, which explains its purpose, design, included frameworks/libraries, usage and frequently asked questions. A set of frequently questions, which all templates share see here: Shared FAQ FAQ. It is recommended to use the sidebar to navigate this documentation, since it is very long and cumbersome to scroll through.
cli-python
Purpose
cli-python is a Python based template designed for command line applications, but it may also be easily used as standard Python package without any command line interface. It is an improved version of cookiecutter-hypermodern-python.
Design
pyproject.toml and poetry.lock file.├── AUTHORS.rst
├── .bandit.yml
├── codecov.yml
├── CODE_OF_CONDUCT.rst
├── cookietemple.cfg
├── .cookietemple.yml
├── .darglint
├── Dockerfile
├── docs
│ ├── authors.rst
│ ├── code_of_conduct.rst
│ ├── conf.py
│ ├── index.rst
│ ├── installation.rst
│ ├── make.bat
│ ├── Makefile
│ ├── readme.rst
│ ├── reference.rst
│ ├── requirements.txt
│ ├── _static
│ │ └── custom_cookietemple.css
│ └── usage.rst
├── .editorconfig
├── .flake8
├── .gitattributes
├── .github
│ ├── dependabot.yml
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.md
│ │ ├── feature_request.md
│ │ └── general_question.md
│ ├── labels.yml
│ ├── pull_request_template.md
│ ├── release-drafter.yml
│ └── workflows
│ ├── build_package.yml
│ ├── check_no_SNAPSHOT_master.yml
│ ├── check_patch_release_master_only.yml
│ ├── constraints.txt
│ ├── labeler.yml
│ ├── publish_docs.yml
│ ├── publish_package.yml
│ ├── run_cookietemple_lint.yml
│ ├── run_tests.yml
│ ├── release-drafter.yml
│ └── sync_project.yml
├── .gitignore
├── LICENSE
├── Makefile
├── makefiles
│ ├── Linux.mk
│ └── Windows.mk
├── mypy.ini
├── noxfile.py
├── poetry.lock
├── .pre-commit-config.yaml
├── .prettierignore
├── pyproject.toml
├── README.rst
├── .readthedocs.yml
│ └── project_name
│ ├── __init__.py
│ ├── __main__.py
│ └── py.typed
└── tests
├── __init__.py
└── test_main.py
Included frameworks/libraries
poetry for code packaging
click or no command line interface
nox to automate testing in multiple Python environments
pre-commit to run various code style linters and to enforce a common style
Preconfigured readthedocs
Eight Github workflows:
build_docs.yml, which builds the readthedocs documentation.
build_package.yml, which builds the cli-python package.
publish_package.yml, which publishes the package to PyPi. Note that it only runs on Github release and requires PyPi secrets to be set up.
run_tests, apply codecov to your project/PRs in your project and create automatically a report with the details at codecov.io
main_master_branch_protection: Please read main_master_branch_protection workflow.
release-drafter.yml: Please read release drafter workflow.
run_cookietemple_lint.yml, which runscookietemple linton the project.
sync_project.yml, which syncs the project to the most recent cookietemple template version
We highly recommend to use click (if commandline interface is required) together with pytest.
Usage
The package requires the installation of poetry, nox and nox-poetry.
Then generated cli-python project can be installed using:
make install
or alternatively:
poetry install
Your package is then installed in a custom virtual environment on your machine and can be called from your favorite shell:
<<your_project_name>>
Run all pre-commit tests with:
make test-all
Ensure that you have nox nox-poetry installed (as specified in the .github/workflows/constraints.txt file.
Other make targets include:
make clean
which removes all build files:
make build
which builds source and wheel packages, which can then be used for a PyPi release using:
make release
All possible Makefile commands can be viewed using:
make help
FAQ
Do I need a command line interface?
No you do not need a command line interface. cli-python can also be used as a Python package. Simply remove all command line related code. At some point we will try to offer a version without a command line interface.
flake8 and darglint are very slow
This is a known issue with Google and Numpy doc styles: https://github.com/terrencepreilly/darglint/issues/186 If this is a concern to you feel free to remove darglint.
cli-java
Purpose
cli-java is a Java based template for designed for command line applications, which require a fast startup time. Hence, it is based on GraalVM, which allows for the packaging of the application into small, native self-contained executables. Picocli is used as main library for the design of the command line interface.
Design
The template is based on a standard Maven directory structure. However, it is using Gradle as build tool.
├── build.gradle
├── CODE_OF_CONDUCT.rst
├── cookietemple.cfg
├── .cookietemple.yml
├── Dockerfile
├── docs
│ ├── authors.rst
│ ├── code_of_conduct.rst
│ ├── conf.py
│ ├── index.rst
│ ├── installation.rst
│ ├── make.bat
│ ├── Makefile
│ ├── readme.rst
│ ├── requirements.txt
│ ├── _static
│ │ └── custom_cookietemple.css
│ └── usage.rst
├── .editorconfig
├── .gitattributes
├── .github
│ ├── dependabot.yml
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.md
│ │ ├── feature_request.md
│ │ └── general_question.md
│ ├── pull_request_template.md
│ ├── release-drafter.yml
│ └── workflows
│ ├── build_deploy.yml
│ ├── main_master_branch_protection.yml
│ ├── publish_docs.yml
│ ├── release-drafter.yml
│ ├── run_checkstyle.yml
│ ├── run_cookietemple_lint.yml
│ ├── run_tests.yml
│ └── sync_project.yml
├── .gitignore
├── gradle
│ └── wrapper
│ ├── gradle-wrapper.jar
│ └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── LICENSE
├── Makefile
├── makefiles
│ ├── Linux.mk
│ └── Windows.mk
├── .prettierignore
├── .project
├── README.rst
├── .readthedocs.yml
├── .settings
│ └── org.eclipse.buildship.core.prefs
├── settings.gradle
└── src
├── main
│ └── java
│ └── com
│ └── organization
│ └── Exploding_springfield.java
└── test
└── java
└── com
└── organization
├── Exploding_springfieldImageTest.java
├── Exploding_springfieldTest.java
└── NativeImageHelper.java
Included frameworks/libraries
Gradle as build tool
GraalVM as main JDK and virtual layer to allow for native binaries
GraalVM Native Image to build platform dependent self-contained executables
JUnit 5 as main testing framework
Picocli to implement the command line interface
Preconfigured readthedocs
Seven Github workflows:
build_docs.yml, which builds the Read the Docs documentation.
build_deploy.yml, which builds the cli-java project into Linux, MacOS and Windows executables. They are deployed as build artifacts.
run_checkstyle.yml, which runs checkstyle linting using Google’s ruleset.
run_tests.yml, which runs all JUnit tests.
main_master_branch_protection: Please read main_master_branch_protection workflow.
release-drafter.yml: Please read release drafter workflow.
run_cookietemple_lint.yml, which runscookietemple linton the project.
sync_project.yml, which syncs the project to the most recent cookietemple template version
Usage
cli-java requires you to have Gradle, GraalVM and GraalVM Native Image installed. Please follow the instructions on the respective websites to install them. Ensure that GraalVM is the default JDK by running java –version
A platform dependent executable (of the current running operating system!) can then be build by invoking:
make binary
or alternatively:
gradle build
Your platform dependent executable can then be found in the folder build/native-image.
Alternatively you can directly build and run your binary by invoking:
make run
All tests can be run by:
make test
Other make targets include:
make clean
which removes all build files:
make dist
All possible Makefile commands can be viewed using:
make help
FAQ
Can I use cli-java without GraalVM?
cli-java is purposefully designed with GraalVM and native images in mind. We advise against using it without GraalVM.
How can I access the build artifacts?
Go to the Github Actions tab, select the build_deploy workflow and there you can find the artifacts. Note that the workflow must have completed successfully for all operating systems.
gui-java
Purpose
Design
pom.xml file, the tool source code is in src/java and the tests in src/test.cookiejardealer, the file tree looks as follows:├── CODE_OF_CONDUCT.rst
├── cookietemple.cfg
├── .cookietemple.yml
├── Dockerfile
├── docs
│ ├── authors.rst
│ ├── code_of_conduct.rst
│ ├── conf.py
│ ├── index.rst
│ ├── installation.rst
│ ├── make.bat
│ ├── Makefile
│ ├── readme.rst
│ ├── requirements.txt
│ ├── _static
│ │ └── custom_cookietemple.css
│ └── usage.rst
├── .editorconfig
├── .github
│ ├── dependabot.yml
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.md
│ │ ├── feature_request.md
│ │ └── general_question.md
│ ├── pull_request_template.md
│ ├── release-drafter.yml
│ └── workflows
│ ├── compile_package.yml
│ ├── main_master_branch_protection.yml
│ ├── publish_docs.yml
│ ├── release-drafter.yml
│ ├── run_cookietemple_lint.yml
│ ├── run_java_linting.yml
│ ├── run_tests.yml
│ └── sync_project.yml
├── .gitignore
├── LICENSE
├── Makefile
├── makefiles
│ ├── Linux.mk
│ └── Windows.mk
├── pom.xml
├── .prettierignore
├── README.rst
├── .readthedocs.yml
└── src
├── main
│ ├── java
│ │ ├── module-info.java
│ │ └── org
│ │ └── organization
│ │ ├── FXMLController.java
│ │ └── MainApp.java
│ └── resources
│ └── org
│ └── organization
│ ├── scene.fxml
│ └── styles.css
└── test
└── java
└── org
└── organization
├── SimpleClickableButtonTest.java
└── SimpleJUnit5ExampleTest.java
Included frameworks/libraries
Apache Maven to build and solve dependencies
JavaFX (14) to build a graphical user interface
JavaFX Maven plugin to build a modular package with a JRE
Packaging using warp to create a single, distributable, platform specific binary
JUnit 5 for unit tests
TestFX for JavaFX GUI tests
Preconfigured readthedocs
Eight Github workflows:
build_docs.yml, which builds the readthedocs documentation.
compile_package.yml, which compiles the gui-java project.
run_java_linting.yml, which runs checkstyle linting using Google’s ruleset.
run_tests.yml, which runs the Unit tests. Note that this workflow is currently disabled, since GUI unittests are not possible using Github Actions.
run_codecov, apply codecov to your project/PRs in your project and create automatically a report with the details at codecov.io
main_master_branch_protection: Please read main_master_branch_protection workflow.
release-drafter.yml: Please read release drafter workflow. 8.run_cookietemple_lint.yml, which runscookietemple linton the project.
sync_project.yml, which syncs the project to the most recent cookietemple template version.
Usage
The generated gui-java project can be installed using:
make install
Other make targets include:
make clean
which removes all build files:
make dist
which runs jlink to build the gui-java project with a custom platform dependent JRE.
Be aware, that this results in six folders. The executable binary can be found in the target/bin folder and is called launcher.
If you want to package the resulting custom JRE together with the launcher and all other required files (aka the six folders), then run the:
make binary
goal. make binary calls the make dist goal and then packages the files into a single, platform dependent executable using Packaging using warp.
This executable can then be easily distributed.
Tests can be run via:
make test
All possible Makefile commands can be viewed using:
make help
FAQ
None yet.
lib-cpp
Purpose
A template for modern C++ projects - both executables and libraries - using CMake, Clang-Format, CI, unit testing and more, with support for downstream inclusion.
Design
The template is inspired by several others (mainly TheLartians’ and Jason Turner’s <https://github.com/lefticus/cpp_starter_project>). It is using CMake as its build system.
├── .clang-format
├── .clang-tidy
├── cmake
│ ├── CompilerWarnings.cmake
│ ├── Conan.cmake
│ ├── Doxygen.cmake
│ ├── exploding-springfieldConfig.cmake.in
│ ├── SourcesAndHeaders.cmake
│ ├── StandardSettings.cmake
│ ├── StaticAnalyzers.cmake
│ ├── Utils.cmake
│ ├── Vcpkg.cmake
│ └── version.hpp.in
├── CMakeLists.txt
├── codecov.yaml
├── CODE_OF_CONDUCT.rst
├── CONTRIBUTING.rst
├── cookietemple.cfg
├── .cookietemple.yml
├── Dockerfile
├── docs
│ ├── authors.rst
│ ├── code_of_conduct.rst
│ ├── conf.py
│ ├── index.rst
│ ├── installation.rst
│ ├── make.bat
│ ├── Makefile
│ ├── readme.rst
│ ├── requirements.txt
│ ├── _static
│ │ └── custom_cookietemple.css
│ └── usage.rst
├── .editorconfig
├── .github
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.md
│ │ ├── feature_request.md
│ │ └── general_question.md
│ ├── pull_request_template.md
│ ├── release-drafter.yml
│ └── workflows
│ ├── build_linux.yml
│ ├── build_macos.yml
│ ├── build_windows.yml
│ ├── main_master_branch_protection.yml
│ ├── publish_docs.yml
│ ├── release-drafter.yml
│ ├── release.yml
│ ├── run_cookietemple_lint.yml
│ └── sync_project.yml
├── .gitignore
├── include
│ └── exploding-springfield
│ └── tmp.hpp
├── LICENSE
├── Makefile
├── makefiles
│ ├── Linux.mk
│ └── Windows.mk
├── .prettierignore
├── README.rst
├── .readthedocs.yml
├── src
│ └── tmp.cpp
└── test
├── CMakeLists.txt
└── src
└── tmp_test.cpp
Included frameworks/libraries
Modern CMake configuration and project
An example of a Clang-Format config, inspired from the base Google model, with minor tweaks.
Static analyzers integration, with Clang-Tidy and Cppcheck, the former being the default option
Doxygen support, through the
ENABLE_DOXYGENoption, which can enable if desired_configUnit testing support, through GoogleTest (with an option to enable GoogleMock) or Catch2
Code coverage, enabled by using the
ENABLE_CODE_COVERAGEoption, through Codecov CI integrationPackage manager support, with Conan and Vcpkg, through their respective options
CI workflows for Windows, Linux and MacOS using GitHub Actions, making use of the caching features, to ensure minimum run time
Options to build as a header-only library or executable, not just a static or shared library
CCache integration, for speeding up build times
Usage
Installing
To install an already built project, you need to run the install
target with CMake. For example:
cmake --build build --target install --config Release
# a more general syntax for that command is:
cmake --build <build_directory> --target install --config <desired_config>
Building the project
To build the project, all you need to do, after correctly `installing the project <README.rst#Installing>`_, is run a similar CMake routine to the the one below:
mkdir build/ && cd build/
cmake .. -DCMAKE_INSTALL_PREFIX=/absolute/path/to/custom/install/directory
cmake --build . --target install
Note: The custom
CMAKE_INSTALL_PREFIXcan be omitted if you wish to install in the default install location.
More options that you can set for the project can be found in the
cmake/StandardSettings.cmake
file. For certain options additional
configuration may be needed in their respective *.cmake files (i.e.
Conan needs the CONAN_REQUIRES and might need the CONAN_OPTIONS
to be setup for it work correctly; the two are set in the
cmake/Conan.cmake file).
Generating the documentation
In order to generate documentation for the project, you need to configure the build to use Doxygen. This is easily done, by modifying the workflow shown above as follows:
mkdir build/ && cd build/
cmake .. -D<project_name>_ENABLE_DOXYGEN=1 -DCMAKE_INSTALL_PREFIX=/absolute/path/to/custom/install/directory
cmake --build . --target doxygen-docs
Note: This will generate a
docs\/directory in the **project’s root directory*.*
Running tests
By default, the template uses Google
Test for unit testing. Unit
testing can be disabled in the options, by setting the
ENABLE_UNIT_TESTING (from
cmake/StandardSettings.cmake) to be
false. To run the tests, simply use CTest, from the build directory,
passing the desire configuration for which to run tests for. An example
of this procedure is:
cd build # if not in the build directory already
ctest -C Release # or `ctest -C Debug` or any other configuration you wish to test
# you can also run tests with the `-VV` flag for a more verbose output (i.e.
#GoogleTest output as well)
FAQ
None yet.
pub-thesis-latex
Purpose
Design
thesis.tex and thesis-info.tex.thesis-info.tex mostly defines general information such as name, degree, university etc and thesis.tex includes all other tex files such as abstracts, chapters etc.Figs subfolder and all references should be included in References/references.bib.├── Abstract
│ └── abstract.tex
├── Acknowledgement
│ └── acknowledgement.tex
├── Appendix1
│ └── appendix1.tex
├── Chapter1
│ └── chapter1.tex
├── Chapter2
│ ├── chapter2.tex
│ └── Figs
│ ├── Raster
│ │ ├── minion.png
│ │ ├── TomandJerry.png
│ │ └── WallE.png
│ └── Vector
│ ├── minion.eps
│ ├── TomandJerry.eps
│ └── WallE.eps
├── Chapter3
│ └── chapter3.tex
├── compile-thesis.sh
├── compile-thesis-windows.bat
├── cookietemple.cfg
├── .cookietemple.yml
├── Declaration
│ └── declaration.tex
├── Dedication
│ └── dedication.tex
├── Dockerfile
├── Figs
│ ├── CollegeShields
│ │ ├── Downing.eps
│ │ ├── Downing.pdf
│ │ ├── Fitzwilliam.eps
│ │ ├── Fitzwilliam.pdf
│ │ ├── FitzwilliamRed.eps
│ │ ├── FitzwilliamRed.pdf
│ │ ├── Gonville_and_Caius.jpg
│ │ ├── Kings.eps
│ │ ├── Kings.pdf
│ │ ├── Licenses.md
│ │ ├── Peterhouse.pdf
│ │ ├── Queens.eps
│ │ ├── Queens.pdf
│ │ ├── src
│ │ │ ├── Downing.svg
│ │ │ ├── Kings.svg
│ │ │ ├── Peterhouse.svg
│ │ │ ├── Queens.svg
│ │ │ └── Trinity.svg
│ │ ├── StJohns.eps
│ │ ├── StJohns.pdf
│ │ ├── Trinity.eps
│ │ └── Trinity.pdf
│ ├── University_Crest.eps
│ ├── University_Crest_Long.eps
│ ├── University_Crest_Long.pdf
│ └── University_Crest.pdf
├── .github
│ └── workflows
│ └── build_thesis.yml
├── .gitignore
├── glyphtounicode.tex
├── hooks
│ ├── install.sh
│ └── pre-commit
├── LICENSE
├── Makefile
├── PhDThesisPSnPDF.cls
├── Preamble
│ └── preamble.tex
├── README.rst
├── References
│ └── references.bib
├── sty
│ └── breakurl.sty
├── thesis-info.tex
├── thesis.pdf
├── thesis.ps
├── thesis.tex
└── Variables.ini
Included frameworks/libraries
LaTeX, XeLaTeX and LuaLaTeX support
Draft mode: Draft water mark, timestamp, version numbering and line numbering
Bibtex support
A Github workflow
build_thesis.yml, which builds your thesis in a Docker container
Usage
Building your thesis - LaTeX / PDFLaTeX
Using latexmk (Unix/Linux/Windows)
This template supports latexmk. To generate DVI, PS and PDF run
latexmk -dvi -ps -pdf thesis.tex
Using the make file (Unix/Linux)
The template supports PDF, DVI and PS formats. All three formats can be
generated with the provided Makefile.
To build the PDF version of your thesis, run:
make
This build procedure uses pdflatex with bibtex and will produce
thesis.pdf. To use pdflatex with biblatex, you should run:
make BIB_STRATEGY=biblatex
To use XeLaTeX, you should run:
make BUILD_STRATEGY=xelatex
or with biblatex
make BUILD_STRATEGY=xelatex BIB_STRATEGY=biblatex
To use LuaLaTeX, you should run:
make BUILD_STRATEGY=lualatex
or with biblatex
make BUILD_STRATEGY=lualatex BIB_STRATEGY=biblatex
To produce DVI and PS versions of your document, you should run:
make BUILD_STRATEGY=latex
This will use the latex command to build the document and will
produce thesis.dvi, thesis.ps and thesis.pdf documents. You
will need psutils installed
Clean unwanted files
To clean unwanted clutter (all LaTeX auto-generated files), run:
make clean
Note: the Makefile itself is take from and maintained at
here.
Shell script for PDFLaTeX (Unix/Linux)
Usage: sh ./compile-thesis.sh [OPTIONS] [filename]
[option] compile: Compiles the PhD Thesis
[option] clean: removes temporary files - no filename required
Using the batch file on Windows OS (PDFLaTeX)
Open command prompt and navigate to the directory with the tex file. Run:
compile-thesis-windows.bat.Alternatively, double click on
compile-thesis-windows.bat
Building your thesis - XeLaTeX
Using latexmk (Unix/Linux/Windows)
This template supports XeLaTeX compilation chain. To generate PDF
run
latexmk -xelatex thesis.tex
makeindex thesis.nlo -s nomencl.ist -o thesis.nls
latexmk -xelatex -g thesis.tex
Building your thesis - LuaLaTeX
Using latexmk (Unix/Linux/Windows)
This template supports LuaLaTeX compilation chain. To generate PDF
run
latexmk -pdflatex=lualatex -pdf thesis.tex
Usage details
Thesis information such as title, author, year, degree, etc., and other
meta-data can be modified in thesis-info.tex
Class options
The class file, PhDThesisPSnPDF, is based on the standard book
class
It supports the following custom options in the documentclass in thesis.tex:
(Usage \documentclass[a4paper,11pt,print]{PhDThesisPSnPDF})
a4paper(default as per the University guidelines) ora5paper: Paper size11ptor12pt: The University of Cambridge guidelines recommend using a minimum font size of 11pt (12pt is preferred) and 10pt for footnotes. This template also supports10pt.onesideortwoside(default): This is especially useful for printing double side (twoside) or single side.print: Supports Print and Online Version with different page margins and hyperlink styles. Useprintin the options to activate Print Version with appropriate margins and page layout and view styles. Leaving the options field blank will activate Online version.custommargin: You can alter the margin dimension for both print and online version by using the keywordcustommarginin the options. Then you can define the dimensions of the margin in thepreamble.texfile:\ifsetCustomMargin \RequirePackage[left=37mm,right=30mm,top=35mm,bottom=30mm]{geometry} \setFancyHdr \fi
\setFancyHdrshould be called when using custom margins for proper header/footer dimensions\ifsetMarginis deprecated, please use\ifsetCustomMargininstead.index: Including this option builds the index, which is placed at the end of the thesis.Instructions on how to use the index can be found here.
Note: the package
makeidxis used to create the index.abstract: This option enables only the thesis title page and the abstract with title and author to be printed.chapter: This option enables only the specified chapter and it’s references. Useful for review and corrections.draft: The default draft mode supports some special features such as line numbers, images, and water mark with timestamp and custom text. Position of the text can be modified inpreamble.tex.draftclassic: This mode is similar to the default draft mode in the book class. Images are not loaded.lineno: Enables pagewise line numbering on the outer edge. You can switch-off line numbering by specifyingnolinenoin the options.flushleft: The University recommends using ragged right or flush left alignment for texts. The reason behind this is left justifying a text may exclude a certain readers. Dyslexic people find it hard to read justified text. You can enableraggedrightoption in the document class by passingflushleftargument. Default is flush left and right.
Title page
The front page (title page) resizes to fit your title length. You can
modify the options in thesis-info.tex.
\subtitle(optional): Adds a subtitle to your thesis.\college(optional): This option adds the name of your college on the bottom left.
If \college is defined, the bottom of the title page will look like
this:
King's College 2014
If \college is undefined or blank, the degreedate will be
centered.
2014
The template offers support to having both the college and university crests or just one of the crests.
\collegeshield(optional): Includes college crest in addition to the university crest. This reformats the front page layout.
Abstract separate
A separate abstract with the title of the PhD and the candidate name has to be submitted to the Student Registry. This can be generated using
abstractoption in the document class. Ignore subsequent warnings about skipping sections (if any).To generate the separate abstract and the title page, make sure the following commands are in the preamble section of
thesis.texfile:\ifdefineAbstract \includeonly{Abstract/abstract} \fi
Chapter mode
The chapter mode allows user to only print specific chapters along with references. By default, it excludes everything else in the front matter and appendices. This can done by using
chapteroption in the document class inthesis.tex. Ignore subsequent warnings about skipping sections (if any).To generate the separate abstract and the title page, make sure the following commands are in the preamble section of
thesis.texfile:\ifdefineChapter \includeonly{Chapter3/chapter3} \fi
Draft
draft adds a watermark draft text with timestamp and version
number at the top or the bottom of the page. Pagewise line numbering is
added on every page. draft settings can be tweaked in the
preamble.tex.
Use
draftclassicin the document class options to use the default book class draft mode.To add figures in draft mode (default enabled), in the preamble set
\setkeys{Gin}{draft=false}.draft=truedisables figuresTo change the watermark text
To change the position of the watermark text. Default watermark position is top. The location can be changed to (top / bottom)
To change the draft version. Default draft version is v1.0.
Watermark grayscale value can be modified. Text grayscale value (should be between 0-black and 1-white). Default value is 0.75
Choosing the fonts
PhDThesisPSnPDF currently supports three fonts Times,
Fourier and Latin Modern (default).
times: (The University of Cambridge guidelines recommend using Times). Specifying times option in the document class will usemathptpxorTimesfont with Math Support.fourier: fourier font with math supportdefault (empty): When no font is specified,Latin Modernis used as the default font with Math Support.customfont: Any custom font can be set in preamble by usingcustomfontoption in the document class. Then the custom font can be loaded in preamble.tex in the line:\ifsetCustomFont \RequirePackage{Your_Custom_Font} \fi
Choosing the bibliography style
PhDThesisPSnPDF currently supports two styles authoryear and
numbered (default). Citation style has to be set. You can also
specify custombib style and customise the bibliography.
authoryear: For author-year citation eg., Krishna (2013)numbered: (Default Option) For numbered and sorted citation e.g., [1,5,2]custombib: Define your own bibliography style in thepreamble.texfile.\RequirePackage[square, sort, numbers, authoryear]{natbib}
(Overview of Bibtex-Styles with preview)[http://nodonn.tipido.net/bibstyle.php?]
If you would like to use biblatex instead of natbib. Pass the option
custombibin the documentclass. In thepreamble.texfile, edit the custombib section. Make sure you don’t load the natbib package and you can specify the layout of your references inthesis.texin the reference section. If you are usingbiberas backend, runpdflatex thesis.tex >> biber thesis >> pdflatex thesis.tex >> biber thesis >> pdflatex thesis.tex. If you are using the default natbib package, don’t worry about this.
Choosing the page style
PhDThesisPSnPDF defines 3 different page styles (header and footer).
The following definition is for twoside layout. To choose a page
style, include it in the documentclass options:
\documentclass[PageStyleI]{PhDThesisPSnPDF}. Alternatively, page
style can be changed by adding \pagestyle{PageStyleI} or
\pagestyle{PageStyleII} in thesis.tex. Note: Using
\pagestyle command will override documentclass options when used
globally.
default (leave empty): For Page Numbers in Header (Left Even, Right Odd) and Chapter Name in Header (Right Even) and Section #. Section Name (Left Odd). Blank Footer.Header (Even) : 4 Introduction Header (Odd) : 1.2 Section Name 5 Footer : Empty
PageStyleI: For Page Numbers in Header (Left Even, Right Odd) and Chapter Name next to the Page Number on Even Side (Left Even). Section Number and Section Name and Page Number in Header on Odd Side (Right Odd). Footer is empty. Layout:Header (Even) : 4 | Introduction Header (Odd) : 1.2 Section Name | 5 Footer : Empty
PageStyleII: Chapter Name on Even Side (Left Even) in Header. Section Number and Section Name in Header on Odd Side (Right Odd). Page numbering in footer. Layout:Header (Even) : Introduction Header (Odd) : 1.2 Section Name Footer[centered]: 3
Changing the visual style of chapter headings
The visual style of chapter headings can be modified using the
titlesec package. Edit the following lines in the preamble.tex
file.
\RequirePackage{titlesec}
\newcommand{\PreContentTitleFormat}{\titleformat{\chapter}[display]{\scshape\Large}
{\Large\filleft{\chaptertitlename} \Huge\thechapter}
{1ex}{}
[\vspace{1ex}\titlerule]}
\newcommand{\ContentTitleFormat}{\titleformat{\chapter}[display]{\scshape\huge}
{\Large\filleft{\chaptertitlename} \Huge\thechapter}{1ex}
{\titlerule\vspace{1ex}\filright}
[\vspace{1ex}\titlerule]}
\newcommand{\PostContentTitleFormat}{\PreContentTitleFormat}
\PreContentTitleFormat
Custom settings
The depth for the table of contents can be set using:
\setcounter{secnumdepth}{3} \setcounter{tocdepth}{3}
A depth of [3] indicates to a level of
\subsubsectionor #.#.#.#. Default set as 2.To hide sections from appearing in TOC use:
\tochide\section{Section name}in your TeX filesDefine custom caption style for figure and table caption in
preamble.texusing:\RequirePackage[small,bf,figurename=Fig.,labelsep=space,tableposition=top]{caption}
Uncomment the following lines in
preamble.texto force a figure to be displayed in a particular location. UseHwhen including graphics. NoteHinstead ofh.\usepackage{float} \restylefloat{figure}
Bibliography with Author-Year Citation in
preamble.tex:\RequirePackage[round, sort, numbers, authoryear]{natbib}
Line spacing for the entire document can be specified in
preamble.tex. Uncomment the line spacing you prefer. e.g.,
Nomenclature definition
To use nomenclature in your chapters:
\nomenclature[g-pi]{$\pi$}{ $\simeq 3.14\ldots$}The sort keys have prefix. In this case a prefix of
gis used to denote Greek Symbols, followed by-pior-sort_key. Use a-to separate sort key from the prefixes. The standard prefixes defined in this class are:Aora: Roman SymbolsGorg: Greek SymbolsZorz: Acronyms/AbbreviationsRorr: SuperscriptsSors: SubscriptsXorx: Other Symbols
You can change the Title of Nomenclature to Notations or Symbols in the
preamble.texusing:\renewcommand\nomname{Symbols}
TexStudio’s default compile option doesn’t include nomenclature, to
compile your document with the nomenclature, do the following:
Options >> Configure TexStudio >> Build >> User Commands >> add user command
In add user command type makenomeclature:makenomenclature on the
left pane and makeindex %.nlo -s nomencl.ist -o %.nls on the
execution side. Now you can run the user defined command
makenomenclature from Tools >> User >> makenomenclature.
Alternatively, you can use the compile-thesis-windows.bat file or
run make on Unix / Linux / MacOS
Git hooks
You rarely want to commit changes to your TeX files which are not
reflected in the PDF included in the repo. You can automate this
process, among other things, with a git hook. Install the hook with
make hooks (or see how to do it in ./hooks/install.sh). Now
every time you commit, if any files affecting your build have changed in
this commit and those changes are more recent than the last modification
of thesis.pdf, the default make target will be run and changes
to thesis.pdf will be git added.
Currently, changes to any tex/pdf/eps/png/cls files are picked up. This
can be changed in ./hooks/pre-commit.
Skip the hook with git commit --no-verify.
bash-only.
General guidelines
To restrict the length of the figure caption in List of figures use a [short-title] and {longtitle} for the caption or the section:
`\caption[Caption that you want to appear in TOC]{Actual caption of the figure}` `\section[short]{title}`To exclude sections from being numbered and disable it from appearing in the Table of Contents use or
To only exclude it from being listed in the Table of Contents encapsulate the section command inside the
\tochidecommand.\tochide{\section{Section_Name}}the section will not appear in the Table of Contents, but the section will be numbered.When including figures in your tex file, it’s a good practice to size your picture depending on the page size, instead of using absolute values. In the following example
0.75\textwidthrefers to picture width being set to 75% of the text width.\includegraphics[width=0.75\textwidth]{minion}
Use a
-to separate sort key from the prefixes, eg.,g-pidenotes the Greek symbolpi.
web-website-python
Purpose
This template is a Flask based Web Template that can be customized from two basic layouts and many available frontend templates. It contains all the code, necessary for project setup and automatic deployment on a Linux server. It also provides a GitHub Workflow for automatic CSS linting on push using Stylelint.
Design
The whole template is designed to be as customizable as possible. Note that all templates could be customized with a full featured Frontend template setup during the template creation process. However, if you don´t like the offered templates or simply want to create your own frontend, you can create your template with only a minimal frontend. You can choose from two main options:
The basic setup
The basic theme is designed to provide only minimal code needed for getting started: Thus it comes with only minimal HTML/CSS/JS code (but you can initalize it with a full featured frontend, if you want to) and basic Flask configuration. However, it contains all the code needed for automatic deployment on a Linux server and adheres to the cookietemple project structure standards.
├── .bandit.yml
├── CODE_OF_CONDUCT.rst
├── cookietemple.cfg
├── .cookietemple.yml
├── deployment_scripts
│ ├── exploding_springfield
│ ├── exploding_springfield.service
│ ├── README.md
│ └── setup.sh
├── Dockerfile
├── docs
│ ├── authors.rst
│ ├── code_of_conduct.rst
│ ├── conf.py
│ ├── index.rst
│ ├── installation.rst
│ ├── make.bat
│ ├── Makefile
│ ├── readme.rst
│ ├── requirements.txt
│ ├── _static
│ │ └── custom_cookietemple.css
│ └── usage.rst
├── .editorconfig
├── exploding_springfield
│ ├── app.py
│ ├── basic
│ │ ├── __init__.py
│ │ └── routes.py
│ ├── config.py
│ ├── errors
│ │ ├── handlers.py
│ │ └── __init__.py
│ ├── __init__.py
│ ├── server.py
│ ├── static
│ │ └── assets
│ │ ├── css
│ │ │ └── min_css.css
│ │ ├── images
│ │ │ └── gitkeep
│ │ ├── js
│ │ │ └── min_jss.js
│ │ ├── sass
│ │ │ ├── base
│ │ │ │ └── gitkeep
│ │ │ ├── components
│ │ │ │ └── gitkeep
│ │ │ ├── layout
│ │ │ │ └── gitkeep
│ │ │ └── libs
│ │ │ └── gitkeep
│ │ └── webfonts
│ │ └── gitkeep
│ └── templates
│ ├── basic_index.html
│ └── errors
│ ├── 400.html
│ ├── 403.html
│ ├── 404.html
│ ├── 410.html
│ ├── 500.html
│ └── error_template.html
├── .github
│ ├── dependabot.yml
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.md
│ │ ├── feature_request.md
│ │ └── general_question.md
│ ├── pull_request_template.md
│ ├── release-drafter.yml
│ └── workflows
│ ├── build_package.yml
│ ├── main_master_branch_protection.yml
│ ├── publish_docs.yml
│ ├── release-drafter.yml
│ ├── run_bandit.yml
│ ├── run_codecov.yml
│ ├── run_cookietemple_lint.yml
│ ├── run_css_lint.yml
│ ├── run_flake8_linting.yml
│ ├── run_tox_testsuite.yml
│ └── sync_project.yml
├── .gitignore
├── LICENSE
├── Makefile
├── makefiles
│ ├── Linux.mk
│ └── Windows.mk
├── MANIFEST.in
├── .prettierignore
├── README.rst
├── .readthedocs.yml
├── requirements_dev.txt
├── requirements.txt
├── setup.cfg
├── setup.py
├── .stylelintrc.json
├── tests
│ ├── __init__.py
│ └── test_exploding_springfield.py
└── tox.ini
The advanced setup
The advanced theme comes with a lot more functionality by default (and can also be initialized with a full featured, nice frontend):
It uses FlaskSQL-Alchemy and FlaskMigrate to setup a SQLite application for simple User Login.
It provides translation for German and English using Flask-Babel.
It provides sending mail through Flask-Mail.
It provides error handling through custom error pages.
Its configured to be automatically deployed in seconds on a Linux server.
More is WIP (Contributions are welcome).
├── babel.cfg
├── .bandit.yml
├── CODE_OF_CONDUCT.rst
├── cookietemple.cfg
├── .cookietemple.yml
├── deployment_scripts
│ ├── exploding_springfield
│ ├── exploding_springfield.service
│ ├── README.md
│ └── setup.sh
├── Dockerfile
├── docs
│ ├── authors.rst
│ ├── code_of_conduct.rst
│ ├── conf.py
│ ├── index.rst
│ ├── installation.rst
│ ├── make.bat
│ ├── Makefile
│ ├── readme.rst
│ ├── requirements.txt
│ ├── _static
│ │ └── custom_cookietemple.css
│ └── usage.rst
├── .editorconfig
├── exploding_springfield
│ ├── app.py
│ ├── auth
│ │ ├── forms
│ │ │ ├── __init__.py
│ │ │ ├── login_form.py
│ │ │ └── register_form.py
│ │ ├── __init__.py
│ │ └── routes.py
│ ├── config.py
│ ├── errors
│ │ ├── handlers.py
│ │ └── __init__.py
│ ├── __init__.py
│ ├── main
│ │ ├── __init__.py
│ │ └── routes.py
│ ├── models
│ │ ├── __init__.py
│ │ └── users.py
│ ├── server.py
│ ├── services
│ │ └── __init__.py
│ ├── static
│ │ ├── assets
│ │ │ ├── css
│ │ │ │ └── min_css.css
│ │ │ ├── images
│ │ │ │ └── gitkeep
│ │ │ ├── js
│ │ │ │ └── min_jss.js
│ │ │ ├── sass
│ │ │ │ ├── base
│ │ │ │ │ └── gitkeep
│ │ │ │ ├── components
│ │ │ │ │ └── gitkeep
│ │ │ │ ├── layout
│ │ │ │ │ └── gitkeep
│ │ │ │ └── libs
│ │ │ │ └── gitkeep
│ │ │ └── webfonts
│ │ │ └── gitkeep
│ │ └── mail_stub.conf
│ ├── templates
│ │ ├── auth
│ │ │ ├── login.html
│ │ │ └── register.html
│ │ ├── base.html
│ │ ├── errors
│ │ │ ├── 400.html
│ │ │ ├── 403.html
│ │ │ ├── 404.html
│ │ │ ├── 410.html
│ │ │ ├── 500.html
│ │ │ └── error_template.html
│ │ └── index.html
│ └── translations
│ └── de
│ └── LC_MESSAGES
│ └── messages.po
├── .github
│ ├── dependabot.yml
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.md
│ │ ├── feature_request.md
│ │ └── general_question.md
│ ├── pull_request_template.md
│ ├── release-drafter.yml
│ └── workflows
│ ├── build_package.yml
│ ├── main_master_branch_protection.yml
│ ├── publish_docs.yml
│ ├── release-drafter.yml
│ ├── run_bandit.yml
│ ├── run_codecov.yml
│ ├── run_cookietemple_lint.yml
│ ├── run_css_lint.yml
│ ├── run_flake8_linting.yml
│ ├── run_tox_testsuite.yml
│ └── sync_project.yml
├── .gitignore
├── LICENSE
├── Makefile
├── makefiles
│ ├── Linux.mk
│ └── Windows.mk
├── MANIFEST.in
├── .prettierignore
├── README.rst
├── .readthedocs.yml
├── requirements_dev.txt
├── requirements.txt
├── setup.cfg
├── setup.py
├── .stylelintrc.json
├── tests
│ ├── __init__.py
│ └── test_exploding_springfield.py
└── tox.ini
Included frameworks/libraries
Both templates are based on Flask and, in the case of the advanced layout, make heavy use of its extensions.
Preconfigured tox to run pytest matrices with different Python environments
Preconfigured readthedocs
6. Eleven Github workflows: ├── build_package.yml
│ ├── main_master_branch_protection.yml │ ├── publish_docs.yml │ ├── release-drafter.yml │ ├── run_bandit.yml │ ├── run_codecov.yml │ ├── run_cookietemple_lint.yml │ ├── run_css_lint.yml │ ├── run_flake8_linting.yml │ ├── run_tox_testsuite.yml │ └── sync_project.yml
publish_docs.yml, which builds and publishes the readthedocs documentation.
build_package.yml, which builds the web-template package.
run_flake8_linting.yml, which runs flake8 linting.
run_tox_testsuite.yml, which runs the tox testing suite.
run_css_lint.yml, which runs Stylelint CSS linting.
run_codecov, apply codecov to your project/PRs in your project and create automatically a report with the details at codecov.io
run_bandit, run bandit to discover security issues in your python code
main_master_branch_protection: Please read main_master_branch_protection workflow.
release-drafter.yml: Please read release drafter workflow.
run_cookietemple_lint.yml, which runscookietemple linton the project.
sync_project.yml, which syncs the project to the most recent cookietemple template version
We highly recommend to use click (if commandline interface is required) together with pytest.
The advanced template therefore uses some more packages including:
Flask-Babel for translations
Flask-Mail for mail
Flask-Bootstrap for basic login page styling
Flask-Login for login session management
Flask-wtf for the login forms
Usage
The basic template usage
The generated flask web project can be installed using:
$ make install
or alternatively:
$ python setup.py install
Your package is then installed globally (or in your virtual environment) on your machine and can be called from your favorite shell:
$ <<your_project_name>>
Other make targets include:
$ make clean
which removes all build files:
$ make dist
which builds source and wheel packages, which can then be used for a PyPi release using:
$ make release
All possible Makefile commands can be viewed using:
$ make help
Another possibility is to simply run:
$ export FLASK_APP = path/to/your/app.py
$ flask run
Note that, if your current directory contains your app.py file, you do not need to set the environment variable lika above!
The advanced template usage
Using the advanced template, you have to consider a few more steps in order to make it work properly:
You can install the project just like described above via
$ make install.Now, you have to setup and initialize your SQLite database file using
$ make init_db. This step is needed otherwise your app won’t work!In order to make your translations working, we need to update and compile the recent translations Therefore
$ flask translate updateand then$ flask translate compile. Note that you have to$ export FLASK_APP=your/path/to/app.pyif not already done. Then, again, run$ make installto pick up your translations into your actual build.
Now, fire up
$ <<your_project_name>>and see your project setup working.
A quick note on translations: Your advanced template comes with a basic translation setup for German and English translation. As your project grows, you may need to add new translations. This can be easily done using the provided cli-commands by the template:
1. If you want to add a new language: Use $ flask translate init <<my_new_language>>. Note that my new language must be a valid language literal like
en for english.
$ flask translate updateto update all language repositoriesNow you can update your translations in
your/path/to/translations/yourlanguage/LC_MESSAGES/messages.po.
$ flask translate compileto compile all language repositories
Note that you need to run $ make install each time after updating and compiling your new translations in order for them to take effect. However, this is not
necessary, if you start your application via $ flask run.
Automatic Deployment
IMPORTANT: Note that the following is written for a server running Ubuntu 18.04 LTS where Python2 is still the default. If you are using Ubuntu 20 (or similar), you can replace
pip3 with pip and python3 with python.
Both templates are ready for deployment using nginx and gunicorn and are therefore shipped with a setup script path/to/your/project/deployment_scripts/setup.sh.
There are a few requirements needed in order to deploy:
You need a registered Domain from your preferred DNS-Provider like Namecheap.
You need a Linux server, like a droplet at DigitalOcean, in order to deploy your application.
To start deployment, you have to setup your server initially. You can follow, for example, the steps here in order to correctly setup your server.
If you meet all the requirements above login (for example via $ ssh yourvmusername@your-servers-IP) into your server:
Now, you need to clone your repository in order to start the deployment process.
So $ git clone <<GITHUB_URL_OF_YOUR_PROJECT>> and cd $ YOUR_PROJECTS_TOP_LEVEL_DIRECTORY.
Now simply run $ source deployment_scripts/setup.sh and the deployment starts. You may be prompted for your password as some commands run need sudo rights.
Important:
Currently, one more step is required to get https redirecting to work properly. This will be included into a script in the future, to automate this process.
$ sudo vim /etc/nginx/sites-enabled/<<my_project_name>>Now, you need to copy the certbot added section from the second server section into the first server section, so copy:
listen 443 ssl; # managed by Certbotssl_certificate /etc/letsencrypt/live/<<my_url>>/fullchain.pem; # managed by Certbotssl_certificate_key /etc/letsencrypt/live/<<my_url>>/privkey.pem; # managed by Certbotinclude /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbotssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbotinto the first server section after the
locationand delete it from the second one.
$ sudo nginx -t
$ sudo nginx -s reload
$ sudo systemctl restart <<my_project_name>>
Tip: You can check $ sudo systemctl status <my_project_name> to check for the working state of your gunicorn instance or any errors.
If everything went fine, you should now be able to access your application at your domain. Note that the setup process also includes HTTP to HTTPS redirecting.
In case of any problems, dont hesitate to drop us a message in our Discord. or create an issue at our github repo
FAQ
None yet.
Github Support
Overview
cookietemple uses GitPython and PyGithub to automatically create a repository, add, commit and push all files. Moreover, issue labels, a development and a TEMPLATE branch are created. The TEMPLATE branch is required for Syncing your project to work and should not be touched manually.
Branches
Overview
git branches can be understood as diverging copies of the main line of development and facilitate parallel development.
To learn more about branches read Branches in a Nutshell of the Pro Git Book.
A simple best practice development workflow follows the pattern that the master/main branch always contains the latest released code.
It should only be touched for new releases. Code on the master/main branch must compile and be as bug free as possible.
Development takes place on the development branch. All in parallel developed features eventually make it into this branch.
The development branch should always compile, but it may contain incomplete features or known bugs.
cookietemple creates a TEMPLATE branch, which is required for Syncing your project to work and should not be touched manually.
Branch protection rules
cookietemple sets several branch protection rules, which enforce a minimum standard of best branch practices.
For more information please read about protected branches.
The following branch protection rules only apply to the master/main branch:
Required review for pull requests: A pull request to
master/maincan only be merged if the code was at least reviewed by one person. If you are developing alone you can merge with your administrator powers.Dismiss stale pull request approvals when new commits are pushed.
Github Actions
Overview
Modern development tries to merge new features and bug fixes as soon as possible into the development branch, since big, diverging branches are more likely to lead to merge conflicts.
This practice is known as continuous integration (CI).
Continuous integration is usually complemented with automated tests and continuous delivery (CD).
All of cookietemple’s templates feature Github Actions as main CI/CD service.
Please read the Github Actions Overview for more information.
On specific conditions (usually push events), the Github Actions workflows are triggered and executed.
The developers should ensure that all workflows always pass before merging, since they ensure that the package still builds and all tests are executed successfully.
main_master_branch_protection workflow
All templates feature main_master_branch_protection workflow.
This workflow runs everytime a PR to your projects master or main branch is created. It fails, if the PR to the master/main branch
origins from a branch that does not contain patch or release in its branch name.
If development code is written on a branch called development``and a new release of the project is to be made,
one should create a ``release branch only for this purpose and then merge it into master/main branch.
This ensures that new developments can already be merged into development, while the release is finally prepared.
The patch branch should be used for required hotfixes (checked out directly from master/main branch) because, in the meantime, there might
multiple developments going on at development branch and you dont want to interfere with them.
Pull requests against the master or main branch should not contain any SNAPSHOT versions, since they are only used for development versions.
release drafter workflow
All templates feature release-drafter workflow.
This workflow consists of two parts: Everytime a new PR is made, the workflow runs and tries autolabeling the PR either as
feature or bug. Feature PRs introduce new features if the branch name contains “feature”. Bug PRs are PRs that either have a title containing
“fix” or the branch name contains “fix”.
This Action then drafts a new release grouped by the different PR categories and include references and titles to all PRs inclduded in the new release.
One can read more about this at the Release drafter GitHub repo.
sync_project.yml
All templates also feature this workflow. This workflow is used for automatic syncing (if enabled) your project with the latest cookietemple template version.
The workflow is run every night, although this behavior can be customized if desired.
The workflow calls cookietemple sync, which first checks whether a new template version is available and if so it submits a pull request.
For more details please visit Syncing your project.
Secrets
Github secrets are what their name suggests: Encrypted secret values in a repository or an organisation; once they are set their value can be used for sensible data in a project or an organisation but their raw value can never be seen again even by an administrator (but it can be updated).
Cookietemple uses a secret called CT_SYNC_TOKEN for its syncing feature. This secret is automatically created during the repo creation process, if you choose to create a GitHub repo.
The secret contains your encrypted personal access token as its value. Note that this will have no effect on how to login or any other activity in your project.
If you remove the secret or change its value (even with another personal access token of you) the syncing feature will no longer work.
In case you are creating an organisation repository, the secret will also be stored as a repository secret, only usable for your specific project.
See section below in case your Github repo creation failed during the create process.
Error Handling due to failed Github repository creation
Errors during the create process due to a failed Github repo creation may occur due to a vast amount of reasons: Some common error sources are:
You have no active internet connection or your firewall protects you against making calls to external APIs.
2. The Github API service or Github itself is unreachable at the moment, which can happen from time to time. In doubt, make sure to check the Github status page.
A repo with the same name already exists in your account/your organisation.
Your Github Token/Secret does not have all required permissions (all repository and workflow permissions).
Creation fails, ok: But how can I then access the full features of cookietemple?
You can try to fix the issue (or wait some time on case, for example, when Github is down) and then process to create a Github repository manually.
After this, make sure to create a secret named CT_SYNC_TOKEN with the value of your PAT for your repository. See the Github docs
for more information on how to create a secret.
We’re planning to provide a command like cookietemple config fix-github that tries to create a Github repo, set the secret and all other stuff that is going on during the Github repository creation in the create process in a later version.
Issue labels
cookietemple’s Github support automatically creates issue labels. Currently the following labels are automatically created: 1. dependabot: All templates, which include Dependabot support label all Dependabot pull requests with this label.
Contributing
Contributions are welcome and greatly appreciated! Every little bit helps and credit will always be given. If you have any questions or want to get in touch with the core team feel free to join our Discord server.
You can contribute in many ways:
Types of Contributions
Report Bugs
Report bugs at https://github.com/cookiejar/cookietemple/issues.
If you are reporting a bug, please:
Use the appropriate issue template.
Be as detailed as possible. The more time you invest into describing the bug, the more time we save solving them, effectively allowing us to improve cookietemple at a faster pace.
Be patient. We are passionate, hard workers, but also have demanding full time jobs, which require a lot of our attention.
Fix Bugs
Look through the GitHub issues for bugs. We would appreciate it if you quickly commented on the respective issue and write that you are working on this bug, to minimize the chances of two people working on the same task.
Implement Features
Look through the GitHub issues for features. The same rule also applies to features. Please write if you’re picking up one of the feature suggestions.
Add Templates
Write Documentation
cookietemple could always use more documentation, whether as part of the official cookietemple docs, in docstrings, or even on the web in blog posts, articles, and such.
Submit Feedback
The best way to send feedback is to file an issue here .
If you are proposing a feature:
Use the appropriate GitHub issue
Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)
Get Started!
Ready to contribute? Here’s how to set up cookietemple for local development.
Fork the cookietemple repo on GitHub.
Clone your fork locally
$ git clone git@github.com:your_name_here/cookietemple.git
Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development
$ mkvirtualenv cookietemple
$ cd cookietemple/
$ python setup.py develop
4. Create a branch for local development. Note that you should always start your branch name with either fix or feature so that the Release Drafter GitHub App will handle your PR right.
$ git checkout -b fix_or_feature/name-of-your-bugfix-or-feature
Now you can make your changes locally.
When you’re done making changes, check that your changes pass the nox test suite.
$ nox
To get nox (and nox-poetry), just pip install them into your virtualenv.
Commit your changes and push your branch to GitHub
$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin fix_or_feature/name-of-your-bugfix-or-feature
Submit a pull request through the GitHub website.
Pull Request Guidelines
Before you submit a pull request, check that it meets these guidelines:
The pull request should include tests.
- If the pull request adds functionality, the docs should be updated.Put your new functionality into a function with a docstring, and add the feature to the list in README.rst, if it is a major feature.
The pull request should work for Python 3.7+ and for PyPy. Check your pull request on Github and verify that all checks and GitHub workflows are passing!
Tips
To run a subset of tests:
.. code-block:: console
$ pytest tests/something
Adding new templates
Adding new templates is one of the major improvements and community contributions to cookietemple, which is why we are dedicating a whole section to it.
Please note that creating new templates is a time consuming task. So be prepared to invest a few hours to bring a new template to life.
The integration into cookietemple however, is straightforward if you follow the guide below.
Due to the tight coupling of our templates with all cookietemple commands such as create, list, info, lint and bump-version,
new templates require the modification of several files.
cookietemple uses cookiecutter to create all templates. You need to familiarize yourself beforehand with cookiecutter to able to write templates, but don’t worry, it’s pretty easy and you usually get by with very few cookiecutter variables. You can start with your very first cookiecutter template and then simply see how the other existing cookietemple templates are made and copy what you need.
The following sections will line out the requirements for new templates and guide you through the process of adding new templates step by step. Nevertheless, we strongly encourage you to discuss your proposed template first with us in public via a Github issue.
Template requirements
To keep the standard of our templates high we enforce several standards, to which all templates must adhere. Exceptions, where applicable, but they would have to be discussed beforehand. Hence, the term should.
New templates must be novel. We do not want a second cli-python template, but you are of course always invited to improve it. A new commandline library does not warrant an additional template, but rather modifications of the existing template with cookiecutter if statements. However, distinct modifications of already existing templates may be eligible. An example would be to add a GUI template for a language, which does not yet have a GUI template. Templates for domains, which we do not yet cover or additional languages to already existing domains are of course more than welcome.
All templates should be cutting edge and not be based on technical debt or obscure requirements. Our target audience are enthusiastic open source contributors and not decades old companies stuck with Python 2.7.
All templates should build as automatically as possible and download all dependencies without manual intervention.
All templates must have a testing and possibly mocking framework included.
All templates must provide a readthedocs setup, a README.rst, usage.rst and installation.rst file, a LICENSE, Github issue and pull request templates and a .gitignore file. Moreover, a .dependabot configuration should be present if applicable. Note that most of these are already included in our common_files and do not need to be rewritten. More on that below.
All templates must provide a Makefile, which wraps heavily used commands to unify common operations such as installing, testing or distributing a project.
All templates should have a Dockerfile, which provides an entrypoint for the project.
All templates must implement all required functionality to allow the application of all commands mentioned above to them, which includes a cookietemple.cfg file, the template being in the available_templates.yml and more.
All templates must have Github workflows, which at least build the documentation and the project.
Every template must also have a workflow inside cookietemple, which creates a project from the template with dummy values.
Your template must support Linux and MacOS. Windows support is optional, but strongly encouraged.
Again, we strongly suggest that new templates are discussed with the core team first.
Step by step guide to adding new templates
Let’s assume that we are planning to add a new commandline Brainfuck template to cookietemple.
We discussed our design at length with the core team and they approved our plan. For the sake of this tutorial we assume that the path / always points to /cookietemple.
Hence, at this level we see cookietemple_cli.py and a folder per CLI command.
Let’s add our brainfuck template information to
/create/templates/available_templates.ymlbelow theclisection.
1cli:
2 brainfuck:
3 name: Brainfuck Commandline Tool
4 handle: cli-brainfuck
5 version: 0.0.1
6 available libraries: none
7 short description: Brainfuck Commandline tool with ANSI coloring
8 long description: Amazing brainfuck tool, which can even show pretty unicorns in the console.
9 Due to ANSI coloring support they can even be pink! Please someone send help.
- Next, we add our brainfuck template to
/create/templatesNote that it should adhere to the standards mentioned above and include all required files. Don’t forget to add a cookietemple.cfg file to facilitate bump-version. See Configuration for details. It is mandatory to name the top level folder{{ cookiecutter.project_slug }}, which ensures that the project after creation will have a proper name. Furthermore, thecookiecutter.jsonfile should have at least the following variables:
1{
2"full_name": "Homer Simpson",
3"email": "homer.simpson@posteo.net",
4"project_name": "sample-cli",
5"project_slug": "sample-cli",
6"version": "1.0.0",
7"project_short_description": "Command-line utility to...",
8"github_username": "homer_github"
9}
The file tree of the template should resemble
1├── cookiecutter.json
2└── {{ cookiecutter.project_slug }}
3 ├── docs
4 │ ├── installation.rst
5 │ └── usage.rst
6 ├── .github
7 │ └── workflows
8 │ └── build_brainfuck.yml
9 ├── hello.bf
10 ├── cookietemple.cfg
11 └── README.rst
- Now it is time to subclass the
TemplateCreatorto implement all required functions to create our template!Let’s edit/create/domains/cli_creator.py. Note that for new domains you would simply create a new file called DomainCreator.In this case we suggest to simply copy the code of an existing Creator and adapt it to the new domain. Your new domain may make use of other creation functions instead ofcreate_template_without_subdomain, if they for example contain subdomains. You can examinecreate/TemplatorCreator.pyto see what’s available. You may also remove functions such as the creation of common files.If we have any brainfuck specific cookiecutter variables that we need to populate, we may add them to the TemplateStructCli.Our brainfuck templates does not have them, so we just leave it as is.For the next step we simply go through theCliCreatorclass and add our brainfuck template where required. Moreover, we implement acli_brainfuck_optionsfunction, which we use to prompt for template specific cookiecutter variables.Assumingcli_creator.pyalready contains acli-javatemplate
1@dataclass
2class TemplateStructCli(CookietempleTemplateStruct):
3 """
4 Intended Use: This class holds all attributes specific for CLI projects
5 """
6
7 """______JAVA______"""
8 main_class_prefix: str = ''
9
10 """____BRAINFUCK___"""
11
12
13class CliCreator(TemplateCreator):
14
15 def __init__(self):
16 self.cli_struct = TemplateStructCli(domain='cli')
17 super().__init__(self.cli_struct)
18 self.WD = os.path.dirname(__file__)
19 self.WD_Path = Path(self.WD)
20 self.TEMPLATES_CLI_PATH = f'{self.WD_Path.parent}/templates/cli'
21
22 '"" TEMPLATE VERSIONS ""'
23 self.CLI_JAVA_TEMPLATE_VERSION = super().load_version('cli-java')
24 self.CLI_BRAINFUCK_TEMPLATE_VERSION = super().load_version('cli-brainfuck')
25
26 def create_template(self, path: Path, dot_cookietemple: dict or None):
27 """
28 Handles the CLI domain. Prompts the user for the language, general and domain specific options.
29 """
30
31 self.cli_struct.language = cookietemple_questionary_or_dot_cookietemple(function='select',
32 question='Choose the project\'s primary language',
33 choices=['python', 'java', 'brainfuck'],
34 default='python',
35 dot_cookietemple=dot_cookietemple,
36 to_get_property='language')
37
38 # prompt the user to fetch general template configurations
39 super().prompt_general_template_configuration(dot_cookietemple)
40
41 # switch case statement to prompt the user to fetch template specific configurations
42 switcher = {
43 'java': self.cli_java_options,
44 'brainfuck': self.cli_brainfuck_options
45 }
46 switcher.get(self.cli_struct.language)(dot_cookietemple)
47
48 self.cli_struct.is_github_repo, \
49 self.cli_struct.is_repo_private, \
50 self.cli_struct.is_github_orga, \
51 self.cli_struct.github_orga \
52 = prompt_github_repo(dot_cookietemple)
53
54 if self.cli_struct.is_github_orga:
55 self.cli_struct.github_username = self.cli_struct.github_orga
56
57 # create the chosen and configured template
58 super().create_template_without_subdomain(f'{self.TEMPLATES_CLI_PATH}')
59
60 # switch case statement to fetch the template version
61 switcher_version = {
62 'java': self.CLI_JAVA_TEMPLATE_VERSION,
63 'brainfuck': self.CLI_BRAINFUCK_TEMPLATE_VERSION
64 }
65 self.cli_struct.template_version, self.cli_struct.template_handle = switcher_version.get(
66 self.cli_struct.language.lower()), f'cli-{self.cli_struct.language.lower()}'
67
68 super().process_common_operations(path=Path(path).resolve(), domain='cli', language=self.cli_struct.language, dot_cookietemple=dot_cookietemple)
69
70 def cli_python_options(self, dot_cookietemple: dict or None):
71 """ Prompts for cli-python specific options and saves them into the CookietempleTemplateStruct """
72 self.cli_struct.command_line_interface = cookietemple_questionary_or_dot_cookietemple(function='select',
73 question='Choose a command line library',
74 choices=['Click', 'Argparse', 'No command-line interface'],
75 default='Click',
76 dot_cookietemple=dot_cookietemple,
77 to_get_property='command_line_interface')
78 [...]
79
80 def cli_java_options(self, dot_cookietemple: dict or None) -> None:
81 """ Prompts for cli-java specific options and saves them into the CookietempleTemplateStruct """
82 [...]
83
84 def cli_brainfuck_options(self):
85 """ Prompts for cli-brainfuck specific options and saves them into the CookietempleTemplateStruct """
86 pass
- If a new template were added we would also have to import our new Creator in
create/create.pyand add the new domain to the domain prompt and the switcher.However, in this case we can simply skip this step, sincecliis already included.
1def choose_domain(domain: str):
2 """
3 Prompts the user for the template domain.
4 Creates the .cookietemple file.
5 Prompts the user whether or not to create a Github repository
6 :param domain: Template domain
7 """
8 if not domain:
9 domain = click.prompt('Choose between the following domains',
10 type=click.Choice(['cli', 'gui', 'web', 'pub']))
11
12 switcher = {
13 'cli': CliCreator,
14 'web': WebCreator,
15 'gui': GuiCreator,
16 'pub': PubCreator
17 }
18
19 creator_obj = switcher.get(domain.lower())()
20 creator_obj.create_template()
- Linting is up next! We need to ensure that our brainfuck template always adheres to the highest standards! Let’s edit
lint/domains/cli.py.We need to add a new class, which inherits from TemplateLinter and add our linting functions to it.
1class CliBrainfuckLint(TemplateLinter, metaclass=GetLintingFunctionsMeta):
2 def __init__(self, path):
3 super().__init__(path)
4
5 def lint(self):
6 super().lint_project(self, self.methods)
7
8 def check_sync_section(self) -> bool:
9 """
10 Check the sync_files_blacklisted section containing every required file!
11 """
12 config_linter = ConfigLinter(f'{self.path}/cookietemple.cfg', self)
13 result = config_linter.check_section(section_items=config_linter.parser.items('sync_files_blacklisted'), section_name='sync_files_blacklisted',
14 main_linter=self, blacklisted_sync_files=[[('changelog', 'CHANGELOG.rst')], -1],
15 error_code='cli-brainfuck-2', is_sublinter_calling=True)
16 if result:
17 self.passed.append(('cli-brainfuck-2', 'All required sync blacklisted files are configured!'))
18 else:
19 self.failed.append(('cli-brainfuck-2', 'Blacklisted sync files section misses some required files!'))
20 return result
21
22 def brainfuck_files_exist(self) -> None:
23 """
24 Checks a given pipeline directory for required files.
25 Iterates through the templates's directory content and checkmarks files for presence.
26 Files that **must** be present::
27 'hello.bf',
28 Files that *should* be present::
29 '.github/workflows/build_brainfuck.yml',
30 Files that *must not* be present::
31 none
32 Files that *should not* be present::
33 none
34 """
35
36 # NB: Should all be files, not directories
37 # List of lists. Passes if any of the files in the sublist are found.
38 files_fail = [
39 ['hello.bf'],
40 ]
41 files_warn = [
42 [os.path.join('.github', 'workflows', 'build_brainfuck.yml')],
43 ]
44
45 # List of strings. Fails / warns if any of the strings exist.
46 files_fail_ifexists = [
47
48 ]
49 files_warn_ifexists = [
50
51 ]
52
53 files_exist_linting(self, files_fail, files_fail_ifexists, files_warn, files_warn_ifexists)
We need to ensure that our new linting function is found when linting is applied. Therefore, we turn our eyes to lint/lint.py, import our CliBrainfuckLinter and add it to the switcher.
1from cookietemple.lint.domains.cli import CliBrainfuckLint
2
3switcher = {
4 'cli-python': CliPythonLint,
5 'cli-java': CliJavaLint,
6 'cli-brainfuck': CliBrainfuckLint,
7 'web-website-python': WebWebsitePythonLint,
8 'gui-java': GuiJavaLint,
9 'pub-thesis-latex': PubLatexLint
10}
Our shiny new CliBrainfuckLinter is now ready for action!
- The only thing left to do now is to add a new Github Actions workflow for our template. Let’s go one level up in the folder tree and create
.github/workflows/create_cli_brainfuck.yml.We want to ensure that if we change something in our template, that it still builds!
1name: Create cli-brainfuck Template
2
3on: [push]
4
5jobs:
6 build:
7
8 runs-on: ubuntu-latest
9 strategy:
10 matrix:
11 python: [3.8, 3.9]
12
13 steps:
14 - uses: actions/checkout@v2
15 name: Check out source-code repository
16
17 - name: Setup Python
18 uses: actions/setup-python@v2.2.2
19 with:
20 python-version: ${{ matrix.python }}
21
22 - name: Install Poetry
23 run: |
24 pip install poetry
25
26 - name: Build cookietemple
27 run: |
28 make install
29
30 - name: Create cli-brainfuck Template
31 run: |
32 echo -e "cli\nbrainfuck\nHomer\nhomer.simpson@hotmail.com\nExplodingSpringfield\ndescription\nhomergithub\nn" | poetry run cookietemple create
33
34 - name: Build Package
35 uses: fabasoad/setup-brainfuck-action@master
36 with:
37 version: 0.1.dev1
38 - name: Hello World
39 run: |
40 brainfucky --file ExplodingSpringfield/hello.bf
We were pleasently surprised to see that someone already made a Github Action for brainfuck.
- Finally, we add some documentation to
/docs/available_templates.rstand explain the purpose, design and frameworks/libraries.That’s it! We should now be able to try out your new template using
cookietemple createThe template should be creatable, it should automatically lint after the creation and Github support should be enabled as well! If we runcookietemple listOur new template should show up as well! I’m sure that you noticed that there’s not actually a brainfuck template in cookietemple (yet!).To quote our mighty Math professors: ‘We’ll leave this as an exercise to the reader.’
External Python based projects
To use cookietemple in an external Python based project
import cookietemple
FAQ
cookietemple is compound software and due to its complex nature many questions may arise. This section serves as a collection of frequently asked questions. If you do not find your answer here you may always join our Discord channel and ask for help. We are happy to include your question here afterwards.
I am looking for a template for domain x and language y, but it does not exist yet!
We are always looking to add new templates to cookietemple. Please open an issue or join our Discord channel. Even better if you already have a draft for the template and/or could add it yourself!
Troubleshooting
All currently known issues can be found on our Github issue tracker. If there are any major known issues they will be listed here.
Community
Development Leads
Lukas Heumos (@zethson Github, @Lukas Heumos Twitter)
Philipp Ehmele (@imipenem Github, @Philipp Ehmele Twitter)
Core contributors
None yet. Why not be the first?
Contributors
Filip Dutescu (@filipdutescu Github) (C++ template and more)
Tobias Langes (@adlanto Github) (Windows support)
Contributor Covenant Code of Conduct
Our Pledge
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
Our Standards
Examples of behavior that contributes to creating a positive environment include:
Using welcoming and inclusive language
Being respectful of differing viewpoints and experiences
Gracefully accepting constructive criticism
Focusing on what is best for the community
Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
The use of sexualized language or imagery and unwelcome sexual attention or advances
Trolling, insulting/derogatory comments, and personal or political attacks
Public or private harassment
Publishing others’ private information, such as a physical or electronic address, without explicit permission
Other conduct which could reasonably be considered inappropriate in a professional setting
Our Responsibilities
Maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
Maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
Scope
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project’s leadership.
Attribution
This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html