Available templates#
cookietemple currently has the following templates available:
In the following every template is devoted its own section, which explains its purpose, design, included frameworks/libraries, usage and frequently asked questions. A set of frequently questions, which all templates share see here: Shared FAQ FAQ. It is recommended to use the sidebar to navigate this documentation, since it is very long and cumbersome to scroll through.
cli-python#
Purpose#
cli-python is a Python based template designed for command line applications, but it may also be easily used as standard Python package without any command line interface. It is an improved version of cookiecutter-hypermodern-python.
Design#
pyproject.toml and poetry.lock file.├── AUTHORS.rst
├── .bandit.yml
├── codecov.yml
├── CODE_OF_CONDUCT.rst
├── cookietemple.cfg
├── .cookietemple.yml
├── .darglint
├── Dockerfile
├── docs
│ ├── authors.rst
│ ├── code_of_conduct.rst
│ ├── conf.py
│ ├── index.rst
│ ├── installation.rst
│ ├── make.bat
│ ├── Makefile
│ ├── readme.rst
│ ├── reference.rst
│ ├── requirements.txt
│ ├── _static
│ │ └── custom_cookietemple.css
│ └── usage.rst
├── .editorconfig
├── .flake8
├── .gitattributes
├── .github
│ ├── dependabot.yml
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.md
│ │ ├── feature_request.md
│ │ └── general_question.md
│ ├── labels.yml
│ ├── pull_request_template.md
│ ├── release-drafter.yml
│ └── workflows
│ ├── build_package.yml
│ ├── check_no_SNAPSHOT_master.yml
│ ├── check_patch_release_master_only.yml
│ ├── constraints.txt
│ ├── labeler.yml
│ ├── publish_docs.yml
│ ├── publish_package.yml
│ ├── run_cookietemple_lint.yml
│ ├── run_tests.yml
│ ├── release-drafter.yml
│ └── sync_project.yml
├── .gitignore
├── LICENSE
├── Makefile
├── makefiles
│ ├── Linux.mk
│ └── Windows.mk
├── mypy.ini
├── noxfile.py
├── poetry.lock
├── .pre-commit-config.yaml
├── .prettierignore
├── pyproject.toml
├── README.rst
├── .readthedocs.yml
│ └── project_name
│ ├── __init__.py
│ ├── __main__.py
│ └── py.typed
└── tests
├── __init__.py
└── test_main.py
Included frameworks/libraries#
poetry for code packaging
click or no command line interface
nox to automate testing in multiple Python environments
pre-commit to run various code style linters and to enforce a common style
Preconfigured readthedocs
Eight Github workflows:
build_docs.yml, which builds the readthedocs documentation.
build_package.yml, which builds the cli-python package.
publish_package.yml, which publishes the package to PyPi. Note that it only runs on Github release and requires PyPi secrets to be set up.
run_tests, apply codecov to your project/PRs in your project and create automatically a report with the details at codecov.io
main_master_branch_protection: Please read main_master_branch_protection workflow.
release-drafter.yml: Please read release drafter workflow.
run_cookietemple_lint.yml, which runscookietemple linton the project.
sync_project.yml, which syncs the project to the most recent cookietemple template version
We highly recommend to use click (if commandline interface is required) together with pytest.
Usage#
The package requires the installation of poetry, nox and nox-poetry.
Then generated cli-python project can be installed using:
make install
or alternatively:
poetry install
Your package is then installed in a custom virtual environment on your machine and can be called from your favorite shell:
<<your_project_name>>
Run all pre-commit tests with:
make test-all
Ensure that you have nox nox-poetry installed (as specified in the .github/workflows/constraints.txt file.
Other make targets include:
make clean
which removes all build files:
make build
which builds source and wheel packages, which can then be used for a PyPi release using:
make release
All possible Makefile commands can be viewed using:
make help
FAQ#
Do I need a command line interface?#
No you do not need a command line interface. cli-python can also be used as a Python package. Simply remove all command line related code. At some point we will try to offer a version without a command line interface.
flake8 and darglint are very slow#
This is a known issue with Google and Numpy doc styles: https://github.com/terrencepreilly/darglint/issues/186 If this is a concern to you feel free to remove darglint.
cli-java#
Purpose#
cli-java is a Java based template for designed for command line applications, which require a fast startup time. Hence, it is based on GraalVM, which allows for the packaging of the application into small, native self-contained executables. Picocli is used as main library for the design of the command line interface.
Design#
The template is based on a standard Maven directory structure. However, it is using Gradle as build tool.
├── build.gradle
├── CODE_OF_CONDUCT.rst
├── cookietemple.cfg
├── .cookietemple.yml
├── Dockerfile
├── docs
│ ├── authors.rst
│ ├── code_of_conduct.rst
│ ├── conf.py
│ ├── index.rst
│ ├── installation.rst
│ ├── make.bat
│ ├── Makefile
│ ├── readme.rst
│ ├── requirements.txt
│ ├── _static
│ │ └── custom_cookietemple.css
│ └── usage.rst
├── .editorconfig
├── .gitattributes
├── .github
│ ├── dependabot.yml
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.md
│ │ ├── feature_request.md
│ │ └── general_question.md
│ ├── pull_request_template.md
│ ├── release-drafter.yml
│ └── workflows
│ ├── build_deploy.yml
│ ├── main_master_branch_protection.yml
│ ├── publish_docs.yml
│ ├── release-drafter.yml
│ ├── run_checkstyle.yml
│ ├── run_cookietemple_lint.yml
│ ├── run_tests.yml
│ └── sync_project.yml
├── .gitignore
├── gradle
│ └── wrapper
│ ├── gradle-wrapper.jar
│ └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── LICENSE
├── Makefile
├── makefiles
│ ├── Linux.mk
│ └── Windows.mk
├── .prettierignore
├── .project
├── README.rst
├── .readthedocs.yml
├── .settings
│ └── org.eclipse.buildship.core.prefs
├── settings.gradle
└── src
├── main
│ └── java
│ └── com
│ └── organization
│ └── Exploding_springfield.java
└── test
└── java
└── com
└── organization
├── Exploding_springfieldImageTest.java
├── Exploding_springfieldTest.java
└── NativeImageHelper.java
Included frameworks/libraries#
Gradle as build tool
GraalVM as main JDK and virtual layer to allow for native binaries
GraalVM Native Image to build platform dependent self-contained executables
JUnit 5 as main testing framework
Picocli to implement the command line interface
Preconfigured readthedocs
Seven Github workflows:
build_docs.yml, which builds the Read the Docs documentation.
build_deploy.yml, which builds the cli-java project into Linux, MacOS and Windows executables. They are deployed as build artifacts.
run_checkstyle.yml, which runs checkstyle linting using Google’s ruleset.
run_tests.yml, which runs all JUnit tests.
main_master_branch_protection: Please read main_master_branch_protection workflow.
release-drafter.yml: Please read release drafter workflow.
run_cookietemple_lint.yml, which runscookietemple linton the project.
sync_project.yml, which syncs the project to the most recent cookietemple template version
Usage#
cli-java requires you to have Gradle, GraalVM and GraalVM Native Image installed. Please follow the instructions on the respective websites to install them. Ensure that GraalVM is the default JDK by running java –version
A platform dependent executable (of the current running operating system!) can then be build by invoking:
make binary
or alternatively:
gradle build
Your platform dependent executable can then be found in the folder build/native-image.
Alternatively you can directly build and run your binary by invoking:
make run
All tests can be run by:
make test
Other make targets include:
make clean
which removes all build files:
make dist
All possible Makefile commands can be viewed using:
make help
FAQ#
Can I use cli-java without GraalVM?#
cli-java is purposefully designed with GraalVM and native images in mind. We advise against using it without GraalVM.
How can I access the build artifacts?#
Go to the Github Actions tab, select the build_deploy workflow and there you can find the artifacts. Note that the workflow must have completed successfully for all operating systems.
gui-java#
Purpose#
Design#
pom.xml file, the tool source code is in src/java and the tests in src/test.cookiejardealer, the file tree looks as follows:├── CODE_OF_CONDUCT.rst
├── cookietemple.cfg
├── .cookietemple.yml
├── Dockerfile
├── docs
│ ├── authors.rst
│ ├── code_of_conduct.rst
│ ├── conf.py
│ ├── index.rst
│ ├── installation.rst
│ ├── make.bat
│ ├── Makefile
│ ├── readme.rst
│ ├── requirements.txt
│ ├── _static
│ │ └── custom_cookietemple.css
│ └── usage.rst
├── .editorconfig
├── .github
│ ├── dependabot.yml
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.md
│ │ ├── feature_request.md
│ │ └── general_question.md
│ ├── pull_request_template.md
│ ├── release-drafter.yml
│ └── workflows
│ ├── compile_package.yml
│ ├── main_master_branch_protection.yml
│ ├── publish_docs.yml
│ ├── release-drafter.yml
│ ├── run_cookietemple_lint.yml
│ ├── run_java_linting.yml
│ ├── run_tests.yml
│ └── sync_project.yml
├── .gitignore
├── LICENSE
├── Makefile
├── makefiles
│ ├── Linux.mk
│ └── Windows.mk
├── pom.xml
├── .prettierignore
├── README.rst
├── .readthedocs.yml
└── src
├── main
│ ├── java
│ │ ├── module-info.java
│ │ └── org
│ │ └── organization
│ │ ├── FXMLController.java
│ │ └── MainApp.java
│ └── resources
│ └── org
│ └── organization
│ ├── scene.fxml
│ └── styles.css
└── test
└── java
└── org
└── organization
├── SimpleClickableButtonTest.java
└── SimpleJUnit5ExampleTest.java
Included frameworks/libraries#
Apache Maven to build and solve dependencies
JavaFX (14) to build a graphical user interface
JavaFX Maven plugin to build a modular package with a JRE
Packaging using warp to create a single, distributable, platform specific binary
JUnit 5 for unit tests
TestFX for JavaFX GUI tests
Preconfigured readthedocs
Eight Github workflows:
build_docs.yml, which builds the readthedocs documentation.
compile_package.yml, which compiles the gui-java project.
run_java_linting.yml, which runs checkstyle linting using Google’s ruleset.
run_tests.yml, which runs the Unit tests. Note that this workflow is currently disabled, since GUI unittests are not possible using Github Actions.
run_codecov, apply codecov to your project/PRs in your project and create automatically a report with the details at codecov.io
main_master_branch_protection: Please read main_master_branch_protection workflow.
release-drafter.yml: Please read release drafter workflow. 8.run_cookietemple_lint.yml, which runscookietemple linton the project.
sync_project.yml, which syncs the project to the most recent cookietemple template version.
Usage#
The generated gui-java project can be installed using:
make install
Other make targets include:
make clean
which removes all build files:
make dist
which runs jlink to build the gui-java project with a custom platform dependent JRE.
Be aware, that this results in six folders. The executable binary can be found in the target/bin folder and is called launcher.
If you want to package the resulting custom JRE together with the launcher and all other required files (aka the six folders), then run the:
make binary
goal. make binary calls the make dist goal and then packages the files into a single, platform dependent executable using Packaging using warp.
This executable can then be easily distributed.
Tests can be run via:
make test
All possible Makefile commands can be viewed using:
make help
FAQ#
None yet.
lib-cpp#
Purpose#
A template for modern C++ projects - both executables and libraries - using CMake, Clang-Format, CI, unit testing and more, with support for downstream inclusion.
Design#
The template is inspired by several others (mainly TheLartians’ and Jason Turner’s <https://github.com/lefticus/cpp_starter_project>). It is using CMake as its build system.
├── .clang-format
├── .clang-tidy
├── cmake
│ ├── CompilerWarnings.cmake
│ ├── Conan.cmake
│ ├── Doxygen.cmake
│ ├── exploding-springfieldConfig.cmake.in
│ ├── SourcesAndHeaders.cmake
│ ├── StandardSettings.cmake
│ ├── StaticAnalyzers.cmake
│ ├── Utils.cmake
│ ├── Vcpkg.cmake
│ └── version.hpp.in
├── CMakeLists.txt
├── codecov.yaml
├── CODE_OF_CONDUCT.rst
├── CONTRIBUTING.rst
├── cookietemple.cfg
├── .cookietemple.yml
├── Dockerfile
├── docs
│ ├── authors.rst
│ ├── code_of_conduct.rst
│ ├── conf.py
│ ├── index.rst
│ ├── installation.rst
│ ├── make.bat
│ ├── Makefile
│ ├── readme.rst
│ ├── requirements.txt
│ ├── _static
│ │ └── custom_cookietemple.css
│ └── usage.rst
├── .editorconfig
├── .github
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.md
│ │ ├── feature_request.md
│ │ └── general_question.md
│ ├── pull_request_template.md
│ ├── release-drafter.yml
│ └── workflows
│ ├── build_linux.yml
│ ├── build_macos.yml
│ ├── build_windows.yml
│ ├── main_master_branch_protection.yml
│ ├── publish_docs.yml
│ ├── release-drafter.yml
│ ├── release.yml
│ ├── run_cookietemple_lint.yml
│ └── sync_project.yml
├── .gitignore
├── include
│ └── exploding-springfield
│ └── tmp.hpp
├── LICENSE
├── Makefile
├── makefiles
│ ├── Linux.mk
│ └── Windows.mk
├── .prettierignore
├── README.rst
├── .readthedocs.yml
├── src
│ └── tmp.cpp
└── test
├── CMakeLists.txt
└── src
└── tmp_test.cpp
Included frameworks/libraries#
Modern CMake configuration and project
An example of a Clang-Format config, inspired from the base Google model, with minor tweaks.
Static analyzers integration, with Clang-Tidy and Cppcheck, the former being the default option
Doxygen support, through the
ENABLE_DOXYGENoption, which can enable if desired_configUnit testing support, through GoogleTest (with an option to enable GoogleMock) or Catch2
Code coverage, enabled by using the
ENABLE_CODE_COVERAGEoption, through Codecov CI integrationPackage manager support, with Conan and Vcpkg, through their respective options
CI workflows for Windows, Linux and MacOS using GitHub Actions, making use of the caching features, to ensure minimum run time
Options to build as a header-only library or executable, not just a static or shared library
CCache integration, for speeding up build times
Usage#
Installing#
To install an already built project, you need to run the install
target with CMake. For example:
cmake --build build --target install --config Release
# a more general syntax for that command is:
cmake --build <build_directory> --target install --config <desired_config>
Building the project#
To build the project, all you need to do, after correctly `installing the project <README.rst#Installing>`_, is run a similar CMake routine to the the one below:
mkdir build/ && cd build/
cmake .. -DCMAKE_INSTALL_PREFIX=/absolute/path/to/custom/install/directory
cmake --build . --target install
Note: The custom
CMAKE_INSTALL_PREFIXcan be omitted if you wish to install in the default install location.
More options that you can set for the project can be found in the
cmake/StandardSettings.cmake
file. For certain options additional
configuration may be needed in their respective *.cmake files (i.e.
Conan needs the CONAN_REQUIRES and might need the CONAN_OPTIONS
to be setup for it work correctly; the two are set in the
cmake/Conan.cmake file).
Generating the documentation#
In order to generate documentation for the project, you need to configure the build to use Doxygen. This is easily done, by modifying the workflow shown above as follows:
mkdir build/ && cd build/
cmake .. -D<project_name>_ENABLE_DOXYGEN=1 -DCMAKE_INSTALL_PREFIX=/absolute/path/to/custom/install/directory
cmake --build . --target doxygen-docs
Note: This will generate a
docs\/directory in the **project’s root directory*.*
Running tests#
By default, the template uses Google
Test for unit testing. Unit
testing can be disabled in the options, by setting the
ENABLE_UNIT_TESTING (from
cmake/StandardSettings.cmake) to be
false. To run the tests, simply use CTest, from the build directory,
passing the desire configuration for which to run tests for. An example
of this procedure is:
cd build # if not in the build directory already
ctest -C Release # or `ctest -C Debug` or any other configuration you wish to test
# you can also run tests with the `-VV` flag for a more verbose output (i.e.
#GoogleTest output as well)
FAQ#
None yet.
pub-thesis-latex#
Purpose#
Design#
thesis.tex and thesis-info.tex.thesis-info.tex mostly defines general information such as name, degree, university etc and thesis.tex includes all other tex files such as abstracts, chapters etc.Figs subfolder and all references should be included in References/references.bib.├── Abstract
│ └── abstract.tex
├── Acknowledgement
│ └── acknowledgement.tex
├── Appendix1
│ └── appendix1.tex
├── Chapter1
│ └── chapter1.tex
├── Chapter2
│ ├── chapter2.tex
│ └── Figs
│ ├── Raster
│ │ ├── minion.png
│ │ ├── TomandJerry.png
│ │ └── WallE.png
│ └── Vector
│ ├── minion.eps
│ ├── TomandJerry.eps
│ └── WallE.eps
├── Chapter3
│ └── chapter3.tex
├── compile-thesis.sh
├── compile-thesis-windows.bat
├── cookietemple.cfg
├── .cookietemple.yml
├── Declaration
│ └── declaration.tex
├── Dedication
│ └── dedication.tex
├── Dockerfile
├── Figs
│ ├── CollegeShields
│ │ ├── Downing.eps
│ │ ├── Downing.pdf
│ │ ├── Fitzwilliam.eps
│ │ ├── Fitzwilliam.pdf
│ │ ├── FitzwilliamRed.eps
│ │ ├── FitzwilliamRed.pdf
│ │ ├── Gonville_and_Caius.jpg
│ │ ├── Kings.eps
│ │ ├── Kings.pdf
│ │ ├── Licenses.md
│ │ ├── Peterhouse.pdf
│ │ ├── Queens.eps
│ │ ├── Queens.pdf
│ │ ├── src
│ │ │ ├── Downing.svg
│ │ │ ├── Kings.svg
│ │ │ ├── Peterhouse.svg
│ │ │ ├── Queens.svg
│ │ │ └── Trinity.svg
│ │ ├── StJohns.eps
│ │ ├── StJohns.pdf
│ │ ├── Trinity.eps
│ │ └── Trinity.pdf
│ ├── University_Crest.eps
│ ├── University_Crest_Long.eps
│ ├── University_Crest_Long.pdf
│ └── University_Crest.pdf
├── .github
│ └── workflows
│ └── build_thesis.yml
├── .gitignore
├── glyphtounicode.tex
├── hooks
│ ├── install.sh
│ └── pre-commit
├── LICENSE
├── Makefile
├── PhDThesisPSnPDF.cls
├── Preamble
│ └── preamble.tex
├── README.rst
├── References
│ └── references.bib
├── sty
│ └── breakurl.sty
├── thesis-info.tex
├── thesis.pdf
├── thesis.ps
├── thesis.tex
└── Variables.ini
Included frameworks/libraries#
LaTeX, XeLaTeX and LuaLaTeX support
Draft mode: Draft water mark, timestamp, version numbering and line numbering
Bibtex support
A Github workflow
build_thesis.yml, which builds your thesis in a Docker container
Usage#
Building your thesis - LaTeX / PDFLaTeX#
Using latexmk (Unix/Linux/Windows)#
This template supports latexmk. To generate DVI, PS and PDF run
latexmk -dvi -ps -pdf thesis.tex
Using the make file (Unix/Linux)#
The template supports PDF, DVI and PS formats. All three formats can be
generated with the provided Makefile.
To build the PDF version of your thesis, run:
make
This build procedure uses pdflatex with bibtex and will produce
thesis.pdf. To use pdflatex with biblatex, you should run:
make BIB_STRATEGY=biblatex
To use XeLaTeX, you should run:
make BUILD_STRATEGY=xelatex
or with biblatex
make BUILD_STRATEGY=xelatex BIB_STRATEGY=biblatex
To use LuaLaTeX, you should run:
make BUILD_STRATEGY=lualatex
or with biblatex
make BUILD_STRATEGY=lualatex BIB_STRATEGY=biblatex
To produce DVI and PS versions of your document, you should run:
make BUILD_STRATEGY=latex
This will use the latex command to build the document and will
produce thesis.dvi, thesis.ps and thesis.pdf documents. You
will need psutils installed
Clean unwanted files
To clean unwanted clutter (all LaTeX auto-generated files), run:
make clean
Note: the Makefile itself is take from and maintained at
here.
Shell script for PDFLaTeX (Unix/Linux)#
Usage: sh ./compile-thesis.sh [OPTIONS] [filename]
[option] compile: Compiles the PhD Thesis
[option] clean: removes temporary files - no filename required
Using the batch file on Windows OS (PDFLaTeX)#
Open command prompt and navigate to the directory with the tex file. Run:
compile-thesis-windows.bat.Alternatively, double click on
compile-thesis-windows.bat
Building your thesis - XeLaTeX#
Using latexmk (Unix/Linux/Windows)#
This template supports XeLaTeX compilation chain. To generate PDF
run
latexmk -xelatex thesis.tex
makeindex thesis.nlo -s nomencl.ist -o thesis.nls
latexmk -xelatex -g thesis.tex
Building your thesis - LuaLaTeX#
Using latexmk (Unix/Linux/Windows)#
This template supports LuaLaTeX compilation chain. To generate PDF
run
latexmk -pdflatex=lualatex -pdf thesis.tex
Usage details#
Thesis information such as title, author, year, degree, etc., and other
meta-data can be modified in thesis-info.tex
Class options#
The class file, PhDThesisPSnPDF, is based on the standard book
class
It supports the following custom options in the documentclass in thesis.tex:
(Usage \documentclass[a4paper,11pt,print]{PhDThesisPSnPDF})
a4paper(default as per the University guidelines) ora5paper: Paper size11ptor12pt: The University of Cambridge guidelines recommend using a minimum font size of 11pt (12pt is preferred) and 10pt for footnotes. This template also supports10pt.onesideortwoside(default): This is especially useful for printing double side (twoside) or single side.print: Supports Print and Online Version with different page margins and hyperlink styles. Useprintin the options to activate Print Version with appropriate margins and page layout and view styles. Leaving the options field blank will activate Online version.custommargin: You can alter the margin dimension for both print and online version by using the keywordcustommarginin the options. Then you can define the dimensions of the margin in thepreamble.texfile:\ifsetCustomMargin \RequirePackage[left=37mm,right=30mm,top=35mm,bottom=30mm]{geometry} \setFancyHdr \fi
\setFancyHdrshould be called when using custom margins for proper header/footer dimensions\ifsetMarginis deprecated, please use\ifsetCustomMargininstead.index: Including this option builds the index, which is placed at the end of the thesis.Instructions on how to use the index can be found here.
Note: the package
makeidxis used to create the index.abstract: This option enables only the thesis title page and the abstract with title and author to be printed.chapter: This option enables only the specified chapter and it’s references. Useful for review and corrections.draft: The default draft mode supports some special features such as line numbers, images, and water mark with timestamp and custom text. Position of the text can be modified inpreamble.tex.draftclassic: This mode is similar to the default draft mode in the book class. Images are not loaded.lineno: Enables pagewise line numbering on the outer edge. You can switch-off line numbering by specifyingnolinenoin the options.flushleft: The University recommends using ragged right or flush left alignment for texts. The reason behind this is left justifying a text may exclude a certain readers. Dyslexic people find it hard to read justified text. You can enableraggedrightoption in the document class by passingflushleftargument. Default is flush left and right.
Title page#
The front page (title page) resizes to fit your title length. You can
modify the options in thesis-info.tex.
\subtitle(optional): Adds a subtitle to your thesis.\college(optional): This option adds the name of your college on the bottom left.
If \college is defined, the bottom of the title page will look like
this:
King's College 2014
If \college is undefined or blank, the degreedate will be
centered.
2014
The template offers support to having both the college and university crests or just one of the crests.
\collegeshield(optional): Includes college crest in addition to the university crest. This reformats the front page layout.
Abstract separate#
A separate abstract with the title of the PhD and the candidate name has to be submitted to the Student Registry. This can be generated using
abstractoption in the document class. Ignore subsequent warnings about skipping sections (if any).To generate the separate abstract and the title page, make sure the following commands are in the preamble section of
thesis.texfile:\ifdefineAbstract \includeonly{Abstract/abstract} \fi
Chapter mode#
The chapter mode allows user to only print specific chapters along with references. By default, it excludes everything else in the front matter and appendices. This can done by using
chapteroption in the document class inthesis.tex. Ignore subsequent warnings about skipping sections (if any).To generate the separate abstract and the title page, make sure the following commands are in the preamble section of
thesis.texfile:\ifdefineChapter \includeonly{Chapter3/chapter3} \fi
Draft#
draft adds a watermark draft text with timestamp and version
number at the top or the bottom of the page. Pagewise line numbering is
added on every page. draft settings can be tweaked in the
preamble.tex.
Use
draftclassicin the document class options to use the default book class draft mode.To add figures in draft mode (default enabled), in the preamble set
\setkeys{Gin}{draft=false}.draft=truedisables figuresTo change the watermark text
To change the position of the watermark text. Default watermark position is top. The location can be changed to (top / bottom)
To change the draft version. Default draft version is v1.0.
Watermark grayscale value can be modified. Text grayscale value (should be between 0-black and 1-white). Default value is 0.75
Choosing the fonts#
PhDThesisPSnPDF currently supports three fonts Times,
Fourier and Latin Modern (default).
times: (The University of Cambridge guidelines recommend using Times). Specifying times option in the document class will usemathptpxorTimesfont with Math Support.fourier: fourier font with math supportdefault (empty): When no font is specified,Latin Modernis used as the default font with Math Support.customfont: Any custom font can be set in preamble by usingcustomfontoption in the document class. Then the custom font can be loaded in preamble.tex in the line:\ifsetCustomFont \RequirePackage{Your_Custom_Font} \fi
Choosing the bibliography style#
PhDThesisPSnPDF currently supports two styles authoryear and
numbered (default). Citation style has to be set. You can also
specify custombib style and customise the bibliography.
authoryear: For author-year citation eg., Krishna (2013)numbered: (Default Option) For numbered and sorted citation e.g., [1,5,2]custombib: Define your own bibliography style in thepreamble.texfile.\RequirePackage[square, sort, numbers, authoryear]{natbib}
(Overview of Bibtex-Styles with preview)[http://nodonn.tipido.net/bibstyle.php?]
If you would like to use biblatex instead of natbib. Pass the option
custombibin the documentclass. In thepreamble.texfile, edit the custombib section. Make sure you don’t load the natbib package and you can specify the layout of your references inthesis.texin the reference section. If you are usingbiberas backend, runpdflatex thesis.tex >> biber thesis >> pdflatex thesis.tex >> biber thesis >> pdflatex thesis.tex. If you are using the default natbib package, don’t worry about this.
Choosing the page style#
PhDThesisPSnPDF defines 3 different page styles (header and footer).
The following definition is for twoside layout. To choose a page
style, include it in the documentclass options:
\documentclass[PageStyleI]{PhDThesisPSnPDF}. Alternatively, page
style can be changed by adding \pagestyle{PageStyleI} or
\pagestyle{PageStyleII} in thesis.tex. Note: Using
\pagestyle command will override documentclass options when used
globally.
default (leave empty): For Page Numbers in Header (Left Even, Right Odd) and Chapter Name in Header (Right Even) and Section #. Section Name (Left Odd). Blank Footer.Header (Even) : 4 Introduction Header (Odd) : 1.2 Section Name 5 Footer : Empty
PageStyleI: For Page Numbers in Header (Left Even, Right Odd) and Chapter Name next to the Page Number on Even Side (Left Even). Section Number and Section Name and Page Number in Header on Odd Side (Right Odd). Footer is empty. Layout:Header (Even) : 4 | Introduction Header (Odd) : 1.2 Section Name | 5 Footer : Empty
PageStyleII: Chapter Name on Even Side (Left Even) in Header. Section Number and Section Name in Header on Odd Side (Right Odd). Page numbering in footer. Layout:Header (Even) : Introduction Header (Odd) : 1.2 Section Name Footer[centered]: 3
Changing the visual style of chapter headings#
The visual style of chapter headings can be modified using the
titlesec package. Edit the following lines in the preamble.tex
file.
\RequirePackage{titlesec}
\newcommand{\PreContentTitleFormat}{\titleformat{\chapter}[display]{\scshape\Large}
{\Large\filleft{\chaptertitlename} \Huge\thechapter}
{1ex}{}
[\vspace{1ex}\titlerule]}
\newcommand{\ContentTitleFormat}{\titleformat{\chapter}[display]{\scshape\huge}
{\Large\filleft{\chaptertitlename} \Huge\thechapter}{1ex}
{\titlerule\vspace{1ex}\filright}
[\vspace{1ex}\titlerule]}
\newcommand{\PostContentTitleFormat}{\PreContentTitleFormat}
\PreContentTitleFormat
Custom settings#
The depth for the table of contents can be set using:
\setcounter{secnumdepth}{3} \setcounter{tocdepth}{3}
A depth of [3] indicates to a level of
\subsubsectionor #.#.#.#. Default set as 2.To hide sections from appearing in TOC use:
\tochide\section{Section name}in your TeX filesDefine custom caption style for figure and table caption in
preamble.texusing:\RequirePackage[small,bf,figurename=Fig.,labelsep=space,tableposition=top]{caption}
Uncomment the following lines in
preamble.texto force a figure to be displayed in a particular location. UseHwhen including graphics. NoteHinstead ofh.\usepackage{float} \restylefloat{figure}
Bibliography with Author-Year Citation in
preamble.tex:\RequirePackage[round, sort, numbers, authoryear]{natbib}
Line spacing for the entire document can be specified in
preamble.tex. Uncomment the line spacing you prefer. e.g.,
Nomenclature definition#
To use nomenclature in your chapters:
\nomenclature[g-pi]{$\pi$}{ $\simeq 3.14\ldots$}The sort keys have prefix. In this case a prefix of
gis used to denote Greek Symbols, followed by-pior-sort_key. Use a-to separate sort key from the prefixes. The standard prefixes defined in this class are:Aora: Roman SymbolsGorg: Greek SymbolsZorz: Acronyms/AbbreviationsRorr: SuperscriptsSors: SubscriptsXorx: Other Symbols
You can change the Title of Nomenclature to Notations or Symbols in the
preamble.texusing:\renewcommand\nomname{Symbols}
TexStudio’s default compile option doesn’t include nomenclature, to
compile your document with the nomenclature, do the following:
Options >> Configure TexStudio >> Build >> User Commands >> add user command
In add user command type makenomeclature:makenomenclature on the
left pane and makeindex %.nlo -s nomencl.ist -o %.nls on the
execution side. Now you can run the user defined command
makenomenclature from Tools >> User >> makenomenclature.
Alternatively, you can use the compile-thesis-windows.bat file or
run make on Unix / Linux / MacOS
Git hooks#
You rarely want to commit changes to your TeX files which are not
reflected in the PDF included in the repo. You can automate this
process, among other things, with a git hook. Install the hook with
make hooks (or see how to do it in ./hooks/install.sh). Now
every time you commit, if any files affecting your build have changed in
this commit and those changes are more recent than the last modification
of thesis.pdf, the default make target will be run and changes
to thesis.pdf will be git added.
Currently, changes to any tex/pdf/eps/png/cls files are picked up. This
can be changed in ./hooks/pre-commit.
Skip the hook with git commit --no-verify.
bash-only.
General guidelines#
To restrict the length of the figure caption in List of figures use a [short-title] and {longtitle} for the caption or the section:
`\caption[Caption that you want to appear in TOC]{Actual caption of the figure}` `\section[short]{title}`To exclude sections from being numbered and disable it from appearing in the Table of Contents use or
To only exclude it from being listed in the Table of Contents encapsulate the section command inside the
\tochidecommand.\tochide{\section{Section_Name}}the section will not appear in the Table of Contents, but the section will be numbered.When including figures in your tex file, it’s a good practice to size your picture depending on the page size, instead of using absolute values. In the following example
0.75\textwidthrefers to picture width being set to 75% of the text width.\includegraphics[width=0.75\textwidth]{minion}
Use a
-to separate sort key from the prefixes, eg.,g-pidenotes the Greek symbolpi.
web-website-python#
Purpose#
This template is a Flask based Web Template that can be customized from two basic layouts and many available frontend templates. It contains all the code, necessary for project setup and automatic deployment on a Linux server. It also provides a GitHub Workflow for automatic CSS linting on push using Stylelint.
Design#
The whole template is designed to be as customizable as possible. Note that all templates could be customized with a full featured Frontend template setup during the template creation process. However, if you don´t like the offered templates or simply want to create your own frontend, you can create your template with only a minimal frontend. You can choose from two main options:
The basic setup#
The basic theme is designed to provide only minimal code needed for getting started: Thus it comes with only minimal HTML/CSS/JS code (but you can initialize 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
Eleven Github workflows:
publish_docs.yml, which builds and publishes the readthedocs documentation.
build_package.yml, which builds the web-template package.
run_flake8_linting.yml, which runs flake8 linting.
run_tox_testsuite.yml, which runs the tox testing suite.
run_css_lint.yml, which runs Stylelint CSS linting.
run_codecov, apply codecov to your project/PRs in your project and create automatically a report with the details at codecov.io
run_bandit, run bandit to discover security issues in your python code
main_master_branch_protection: Please read main_master_branch_protection workflow.
release-drafter.yml: Please read release drafter workflow.
run_cookietemple_lint.yml, which runscookietemple linton the project.
sync_project.yml, which syncs the project to the most recent cookietemple template version
We highly recommend to use click (if commandline interface is required) together with pytest.
The advanced template therefore uses some more packages including:
Flask-Babel for translations
Flask-Mail for mail
Flask-Bootstrap for basic login page styling
Flask-Login for login session management
Flask-wtf for the login forms
Usage#
The basic template usage#
The generated flask web project can be installed using:
$ make install
or alternatively:
$ python setup.py install
Your package is then installed globally (or in your virtual environment) on your machine and can be called from your favorite shell:
$ <<your_project_name>>
Other make targets include:
$ make clean
which removes all build files:
$ make dist
which builds source and wheel packages, which can then be used for a PyPi release using:
$ make release
All possible Makefile commands can be viewed using:
$ make help
Another possibility is to simply run:
$ export FLASK_APP = path/to/your/app.py
$ flask run
Note that, if your current directory contains your app.py file, you do not need to set the environment variable lika above!
The advanced template usage#
Using the advanced template, you have to consider a few more steps in order to make it work properly:
You can install the project just like described above via
$ make install.Now, you have to setup and initialize your SQLite database file using
$ make init_db. This step is needed otherwise your app won’t work!In order to make your translations working, we need to update and compile the recent translations Therefore
$ flask translate updateand then$ flask translate compile. Note that you have to$ export FLASK_APP=your/path/to/app.pyif not already done. Then, again, run$ make installto pick up your translations into your actual build.
Now, fire up
$ <<your_project_name>>and see your project setup working.
A quick note on translations: Your advanced template comes with a basic translation setup for German and English translation. As your project grows, you may need to add new translations. This can be easily done using the provided cli-commands by the template:
1. If you want to add a new language: Use $ flask translate init <<my_new_language>>. Note that my new language must be a valid language literal like
en for english.
$ flask translate updateto update all language repositoriesNow you can update your translations in
your/path/to/translations/yourlanguage/LC_MESSAGES/messages.po.
$ flask translate compileto compile all language repositories
Note that you need to run $ make install each time after updating and compiling your new translations in order for them to take effect. However, this is not
necessary, if you start your application via $ flask run.
Automatic Deployment#
IMPORTANT: Note that the following is written for a server running Ubuntu 18.04 LTS where Python2 is still the default. If you are using Ubuntu 20 (or similar), you can replace
pip3 with pip and python3 with python.
Both templates are ready for deployment using nginx and gunicorn and are therefore shipped with a setup script path/to/your/project/deployment_scripts/setup.sh.
There are a few requirements needed in order to deploy:
You need a registered Domain from your preferred DNS-Provider like Namecheap.
You need a Linux server, like a droplet at DigitalOcean, in order to deploy your application.
To start deployment, you have to setup your server initially. You can follow, for example, the steps here in order to correctly setup your server.
If you meet all the requirements above login (for example via $ ssh yourvmusername@your-servers-IP) into your server:
Now, you need to clone your repository in order to start the deployment process.
So $ git clone <<GITHUB_URL_OF_YOUR_PROJECT>> and cd $ YOUR_PROJECTS_TOP_LEVEL_DIRECTORY.
Now simply run $ source deployment_scripts/setup.sh and the deployment starts. You may be prompted for your password as some commands run need sudo rights.
Important:
Currently, one more step is required to get https redirecting to work properly. This will be included into a script in the future, to automate this process.
$ sudo vim /etc/nginx/sites-enabled/<<my_project_name>>Now, you need to copy the certbot added section from the second server section into the first server section, so copy:
listen 443 ssl; # managed by Certbotssl_certificate /etc/letsencrypt/live/<<my_url>>/fullchain.pem; # managed by Certbotssl_certificate_key /etc/letsencrypt/live/<<my_url>>/privkey.pem; # managed by Certbotinclude /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbotssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbotinto the first server section after the
locationand delete it from the second one.
$ sudo nginx -t
$ sudo nginx -s reload
$ sudo systemctl restart <<my_project_name>>
Tip: You can check $ sudo systemctl status <my_project_name> to check for the working state of your gunicorn instance or any errors.
If everything went fine, you should now be able to access your application at your domain. Note that the setup process also includes HTTP to HTTPS redirecting.
In case of any problems, dont hesitate to drop us a message in our Discord. or create an issue at our github repo
FAQ#
None yet.