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 lint
on 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 lint
on 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 lint
on 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_DOXYGEN
option, 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_COVERAGE
option, 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_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
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 size11pt
or12pt
: The University of Cambridge guidelines recommend using a minimum font size of 11pt (12pt is preferred) and 10pt for footnotes. This template also supports10pt
.oneside
ortwoside
(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. Useprint
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 keywordcustommargin
in the options. Then you can define the dimensions of the margin in thepreamble.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 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 specifyingnolineno
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 enableraggedright
option in the document class by passingflushleft
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 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.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 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 usemathptpx
orTimes
font with Math Support.fourier
: fourier font with math supportdefault (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 usingcustomfont
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 thepreamble.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 thepreamble.tex
file, edit the custombib section. Make sure you don’t load the natbib package and you can specify the layout of your references inthesis.tex
in the reference section. If you are usingbiber
as 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
\subsubsection
or #.#.#.#. 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.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. UseH
when including graphics. NoteH
instead 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
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
ora
: Roman SymbolsG
org
: Greek SymbolsZ
orz
: Acronyms/AbbreviationsR
orr
: SuperscriptsS
ors
: SubscriptsX
orx
: 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 add
ed.
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 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 lint
on 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 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.
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 update
to update all language repositoriesNow you can update your translations in
your/path/to/translations/yourlanguage/LC_MESSAGES/messages.po
.
$ 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:
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 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.
$ 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.