Available templates

cookietemple currently has the following templates available:

  1. cli-java

  2. cli-python

  3. gui-java

  4. lib-cpp

  5. pub-thesis-latex

  6. web-website-python

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

The Python package is based on a standard poetry structure with a corresponding 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

  1. poetry for code packaging

  2. click or no command line interface

  3. pytest or unittest as testing frameworks

  4. nox to automate testing in multiple Python environments

  5. pre-commit to run various code style linters and to enforce a common style

  6. Preconfigured readthedocs

  7. Eight Github workflows:

  1. build_docs.yml, which builds the readthedocs documentation.

  2. build_package.yml, which builds the cli-python package.

  3. 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.

  4. run_tests, apply codecov to your project/PRs in your project and create automatically a report with the details at codecov.io

  5. main_master_branch_protection: Please read main_master_branch_protection workflow.

  6. release-drafter.yml: Please read release drafter workflow.

  7. run_cookietemple_lint.yml, which runs cookietemple lint on the project.

  8. 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.

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

  1. Gradle as build tool

  2. GraalVM as main JDK and virtual layer to allow for native binaries

  3. GraalVM Native Image to build platform dependent self-contained executables

  4. JUnit 5 as main testing framework

  5. Picocli to implement the command line interface

  6. Preconfigured readthedocs

  7. Seven Github workflows:

  1. build_docs.yml, which builds the Read the Docs documentation.

  2. build_deploy.yml, which builds the cli-java project into Linux, MacOS and Windows executables. They are deployed as build artifacts.

  3. run_checkstyle.yml, which runs checkstyle linting using Google’s ruleset.

  4. run_tests.yml, which runs all JUnit tests.

  5. main_master_branch_protection: Please read main_master_branch_protection workflow.

  6. release-drafter.yml: Please read release drafter workflow.

  7. run_cookietemple_lint.yml, which runs cookietemple lint on the project.

  8. 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

gui-java is a modular JavaFX based template to build cross platform Desktop graphical user interfaces (GUIs).
It uses Apache Maven to compile the package and Packaging using warp to distribute binaries containing a Java Runtime Environment (JRE).

Design

The template follows the standard Maven directory layout. Therefore, all dependencies are defined in the pom.xml file, the tool source code is in src/java and the tests in src/test.
Please be aware that gui-java is a modular Java 11+ project, which requires a few modifications to distribute and build JavaFX applications. As a result, binaries are a lot smaller. Assuming that your organization is called 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

  1. Apache Maven to build and solve dependencies

  2. JavaFX (14) to build a graphical user interface

  3. JavaFX Maven plugin to build a modular package with a JRE

  4. Packaging using warp to create a single, distributable, platform specific binary

  5. JUnit 5 for unit tests

  6. TestFX for JavaFX GUI tests

  7. Preconfigured readthedocs

  8. Eight Github workflows:

  1. build_docs.yml, which builds the readthedocs documentation.

  2. compile_package.yml, which compiles the gui-java project.

  3. run_java_linting.yml, which runs checkstyle linting using Google’s ruleset.

  4. run_tests.yml, which runs the Unit tests. Note that this workflow is currently disabled, since GUI unittests are not possible using Github Actions.

  5. run_codecov, apply codecov to your project/PRs in your project and create automatically a report with the details at codecov.io

  6. main_master_branch_protection: Please read main_master_branch_protection workflow.

  7. release-drafter.yml: Please read release drafter workflow. 8. run_cookietemple_lint.yml, which runs cookietemple lint on the project.

  8. sync_project.yml, which syncs the project to the most recent cookietemple template version.

Usage

The usage of gui-java is primarily Makefile based. Please be aware that you need Apache Maven and Java 11+ installed.
All (Maven) commands are wrapped into Make commands, but can of course also be called directly:

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

  1. Modern CMake configuration and project

  2. An example of a Clang-Format config, inspired from the base Google model, with minor tweaks.

  3. Static analyzers integration, with Clang-Tidy and Cppcheck, the former being the default option

  4. Doxygen support, through the ENABLE_DOXYGEN option, which can enable if desired_config

  5. Unit testing support, through GoogleTest (with an option to enable GoogleMock) or Catch2

  6. Code coverage, enabled by using the ENABLE_CODE_COVERAGE option, through Codecov CI integration

  7. Package manager support, with Conan and Vcpkg, through their respective options

  8. CI workflows for Windows, Linux and MacOS using GitHub Actions, making use of the caching features, to ensure minimum run time

  9. Options to build as a header-only library or executable, not just a static or shared library

  10. 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_PREFIX can 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

pub-thesis is a latex based template designed for University theses. It is especially suited for Bachelor-, Master theses and dissertations.
The CUED PhD thesis template served as basis for this template.

Design

pub-thesis is a modular latex template, which is reflected in the folder structure. The main tex files are 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.
The tex files for these chapters are found in their respective subfolders.
All figures go inside the 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

  1. LaTeX, XeLaTeX and LuaLaTeX support

  2. Draft mode: Draft water mark, timestamp, version numbering and line numbering

  3. Bibtex support

  4. 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) or a5paper: Paper size

  • 11pt or 12pt: The University of Cambridge guidelines recommend using a minimum font size of 11pt (12pt is preferred) and 10pt for footnotes. This template also supports 10pt.

  • oneside or twoside (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. Use print in 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 keyword custommargin in the options. Then you can define the dimensions of the margin in the preamble.tex file:

    \ifsetCustomMargin
      \RequirePackage[left=37mm,right=30mm,top=35mm,bottom=30mm]{geometry}
      \setFancyHdr
    \fi
    

    \setFancyHdr should be called when using custom margins for proper header/footer dimensions

    \ifsetMargin is deprecated, please use \ifsetCustomMargin instead.

  • 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 makeidx is 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 in preamble.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 specifying nolineno in 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 enable raggedright option in the document class by passing flushleft argument. 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 abstract option 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.tex file:

    \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 chapter option in the document class in thesis.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.tex file:

    \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 draftclassic in 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=true disables figures

  • To 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 use mathptpx or Times font with Math Support.

  • fourier: fourier font with math support

  • default (empty): When no font is specified, Latin Modern is used as the default font with Math Support.

  • customfont: Any custom font can be set in preamble by using customfont option 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 the preamble.tex file.

    \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 custombib in the documentclass. In the preamble.tex file, edit the custombib section. Make sure you don’t load the natbib package and you can specify the layout of your references in thesis.tex in the reference section. If you are using biber as backend, run pdflatex 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 \subsubsection or #.#.#.#. Default set as 2.

  • To hide sections from appearing in TOC use: \tochide\section{Section name} in your TeX files

  • Define custom caption style for figure and table caption in preamble.tex using:

    \RequirePackage[small,bf,figurename=Fig.,labelsep=space,tableposition=top]{caption}
    
  • Uncomment the following lines in preamble.tex to force a figure to be displayed in a particular location. Use H when including graphics. Note H instead of h.

    \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 g is used to denote Greek Symbols, followed by -pi or -sort_key. Use a - to separate sort key from the prefixes. The standard prefixes defined in this class are:

    • A or a: Roman Symbols

    • G or g: Greek Symbols

    • Z or z: Acronyms/Abbreviations

    • R or r: Superscripts

    • S or s: Subscripts

    • X or x: Other Symbols

  • You can change the Title of Nomenclature to Notations or Symbols in the preamble.tex using:

    \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 \tochide command. \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\textwidth refers 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-pi denotes the Greek symbol pi.

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

  1. It uses FlaskSQL-Alchemy and FlaskMigrate to setup a SQLite application for simple User Login.

  2. It provides translation for German and English using Flask-Babel.

  3. It provides sending mail through Flask-Mail.

  4. It provides error handling through custom error pages.

  5. Its configured to be automatically deployed in seconds on a Linux server.

  6. 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.

  1. Flask

  2. click, argparse or no command line interface

  3. pytest or unittest as testing frameworks

  4. Preconfigured tox to run pytest matrices with different Python environments

  5. 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

  1. publish_docs.yml, which builds and publishes the readthedocs documentation.

  2. build_package.yml, which builds the web-template package.

  3. run_flake8_linting.yml, which runs flake8 linting.

  4. run_tox_testsuite.yml, which runs the tox testing suite.

  5. run_css_lint.yml, which runs Stylelint CSS linting.

  6. run_codecov, apply codecov to your project/PRs in your project and create automatically a report with the details at codecov.io

  7. run_bandit, run bandit to discover security issues in your python code

  8. main_master_branch_protection: Please read main_master_branch_protection workflow.

  9. release-drafter.yml: Please read release drafter workflow.

  10. run_cookietemple_lint.yml, which runs cookietemple lint on the project.

  11. 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:

  1. FlaskSQL-Alchemy

  2. Flask-Migrate

  3. Flask-Babel for translations

  4. Flask-Mail for mail

  5. Flask-Bootstrap for basic login page styling

  6. Flask-Login for login session management

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

  1. You can install the project just like described above via $ make install.

  2. 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!

  3. In order to make your translations working, we need to update and compile the recent translations Therefore $ flask translate update and then $ flask translate compile. Note that you have to $ export FLASK_APP=your/path/to/app.py if not already done. Then, again, run $ make install to pick up your translations into your actual build.

  1. 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.

  1. $ flask translate update to update all language repositories

  2. Now you can update your translations in your/path/to/translations/yourlanguage/LC_MESSAGES/messages.po.

  1. $ flask translate compile to 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:

  1. You need a registered Domain from your preferred DNS-Provider like Namecheap.

  2. You need a Linux server, like a droplet at DigitalOcean, in order to deploy your application.

  3. 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.

  1. $ sudo vim /etc/nginx/sites-enabled/<<my_project_name>>

  2. 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 Certbot ssl_certificate /etc/letsencrypt/live/<<my_url>>/fullchain.pem; # managed by Certbot ssl_certificate_key /etc/letsencrypt/live/<<my_url>>/privkey.pem; # managed by Certbot include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

into the first server section after the location and delete it from the second one.

  1. $ sudo nginx -t

  2. $ sudo nginx -s reload

  3. $ 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.

Shared FAQ

How do I publish my documentation?

cookietemple ships with a full, production ready Read the Docs setup and with a complete gh-pages setup.

Read the Docs

You need to import your documentation on Read the Docs website. Do not forget to sync your account first to see your repository. Your documentation will then be available on https://repositoryname.readthedocs.io/

Github Pages

Your documentation is automatically pushed to the gh-pages branch. Follow the documentation on configuring a publishing source for your Github pages site <https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site>`_ and select the gh-pages branch. Your documentation will then be available on ``https://username.github.io/repositoryname.

What is Dependabot and how do I set it up?

Dependabot is a service, which (for supported languages) automatically submits pull requests for dependency updates. cookietemple templates ship with dependabot configurations, if the language is supported by Dependabot. To enable Dependabot you need to login (with your Github account) and add your repository (or enable Dependabot for all repositories). Note that you need to do this for every organization separately. Dependabot will then pick up the configuration and start submitting pull requests!

Release Drafter

In Cookietemple 1.3.0, all templates received a new GitHub Action called Release drafter. This replaces the CHANGELOG.rst file of all templates. Release drafter automatically includes references to all PRs made to the default branch and a description of what this PR was about (basically the PRs title) in a release draft on GitHub. Per default, the release drafter of cookietemple’s templates has been configured to distinguish between two main categories: Features and Fixes. Every PR that was made from a branch called either feature/ (for Features) or fix/ (for Fixes) will automatically be grouped into those categories and be labelled automatically. If no category was found, the changes will be grouped into a common Changes category. See also _release_drafter_workflow.

How do I add a new template?

Please follow Adding new templates.