Merge pull request #11 from Matgenix/documentation

Documentation layout

.gitignore

@@ -69,7 +69,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+doc/_build/
 
 # PyBuilder
 .pybuilder/

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 default_language_version:
   python: python3
-#exclude: '^src/{{ package_name }}/some/directory/'
+exclude: '^doc/'
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.4.0

doc/Makefile

@@ -0,0 +1,72 @@
+# Makefile for Sphinx documentation
+#
+
+# PYVER needs to be major.minor, just "3" doesn't work - it will result in
+# issues with the amendments to PYTHONPATH and install paths (see DIST_VARS).
+
+# Use explicit "version_info" indexing since make cannot handle colon characters, and
+# evaluate it now to allow easier debugging when printing the variable
+
+PYVER:=$(shell python3 -c 'from sys import version_info as v; print("{0}.{1}".format(v[0], v[1]))')
+PYTHON = python$(PYVER)
+
+# You can set these variables from the command line.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= LANG=C sphinx-build
+PAPER         ?=
+# # For merging a documentation archive into a git checkout of numpy/doc
+# # Turn a tag like v1.18.0 into 1.18
+# # Use sed -n -e 's/patttern/match/p' to return a blank value if no match
+# TAG ?= $(shell git describe --tag | sed -n -e's,v\([1-9]\.[0-9]*\)\.[0-9].*,\1,p')
+
+FILES=
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -WT --keep-going -d build/doctrees $(PAPEROPT_$(PAPER)) \
+                  $(SPHINXOPTS) source
+
+.PHONY: help clean html version-check html-build
+
+#------------------------------------------------------------------------------
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  clean     to remove generated doc files and start fresh"
+	@echo "  html      to make standalone HTML files"
+
+clean:
+	-rm -rf build/*
+	find . -name generated -type d -prune -exec rm -rf "{}" ";"
+
+
+#------------------------------------------------------------------------------
+# Automated generation of all documents
+#------------------------------------------------------------------------------
+
+# Build the current QToolKit version, and extract docs from it.
+# We have to be careful of some issues:
+#
+# - Everything must be done using the same Python version
+#
+
+#SPHINXBUILD="LANG=C sphinx-build"
+
+
+#------------------------------------------------------------------------------
+# Basic Sphinx generation rules for different formats
+#------------------------------------------------------------------------------
+generate: build/generate-stamp
+build/generate-stamp: $(wildcard source/reference/*.rst)
+	mkdir -p build
+	touch build/generate-stamp
+
+html: api-doc html-build
+html-build: generate
+	mkdir -p build/html build/doctrees
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html $(FILES)
+	@echo
+	@echo "Build finished. The HTML pages are in build/html."
+api-doc:
+	sphinx-apidoc -e -f -o source/api ../src/qtoolkit

doc/source/_static/index-images/image_licences.txt

@@ -0,0 +1,4 @@
+getting_started.svg: https://www.svgrepo.com/svg/393367/rocket (PD Licence)
+user_guide.svg: https://www.svgrepo.com/svg/75531/user-guide (CC0 Licence)
+api.svg: https://www.svgrepo.com/svg/157898/gears-configuration-tool (CC0 Licence)
+contributor.svg: https://www.svgrepo.com/svg/57189/code-programing-symbol (CC0 Licence)

doc/source/_static/qtoolkit.css

@@ -0,0 +1,162 @@
+@import url('https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,400;0,700;0,900;1,400;1,700;1,900&family=Open+Sans:ital,wght@0,400;0,600;1,400;1,600&display=swap');
+
+:root {
+    --matgenix-color: #46b3c1;
+    --matgenix-dark-color: #338d99;
+}
+
+.navbar-brand img {
+   height: 75px;
+}
+.navbar-brand {
+   height: 75px;
+}
+
+body {
+  font-family: 'Open Sans', sans-serif;
+}
+
+pre, code {
+  font-size: 100%;
+  line-height: 155%;
+}
+
+h1 {
+  font-family: "Lato", sans-serif;
+  color: #013243; /* warm black */
+}
+
+h2 {
+  color: #4d77cf; /* han blue */
+  letter-spacing: -.03em;
+}
+
+h3 {
+  color: #013243; /* warm black */
+  letter-spacing: -.03em;
+}
+
+/* Style the active version button.
+
+- dev: orange
+- stable: green
+- old, PR: red
+
+Colors from:
+
+Wong, B. Points of view: Color blindness.
+Nat Methods 8, 441 (2011). https://doi.org/10.1038/nmeth.1618
+*/
+
+/* If the active version has the name "dev", style it orange */
+#version_switcher_button[data-active-version-name*="dev"] {
+  background-color: #E69F00;
+  border-color: #E69F00;
+  color:#000000;
+}
+
+/* green for `stable` */
+#version_switcher_button[data-active-version-name*="stable"] {
+  background-color: #009E73;
+  border-color: #009E73;
+}
+
+/* red for `old` */
+#version_switcher_button:not([data-active-version-name*="stable"], [data-active-version-name*="dev"], [data-active-version-name=""]) {
+  background-color: #980F0F;
+  border-color: #980F0F;
+}
+
+/* Main page overview cards */
+
+.sd-card {
+  background: #fff;
+  border-radius: 0;
+  padding: 30px 10px 20px 10px;
+  margin: 10px 0px;
+}
+
+.sd-card .sd-card-header {
+  text-align: center;
+}
+
+.sd-card .sd-card-header .sd-card-text {
+  margin: 0px;
+}
+
+.sd-card .sd-card-img-top {
+  height: 52px;
+  width: 52px;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.sd-card .sd-card-header {
+  border: none;
+  background-color: white;
+  color: #150458 !important;
+  font-size: var(--pst-font-size-h5);
+  font-weight: bold;
+  padding: 2.5rem 0rem 0.5rem 0rem;
+}
+
+.sd-card .sd-card-footer {
+  border: none;
+  background-color: white;
+}
+
+.sd-card .sd-card-footer .sd-card-text {
+  max-width: 220px;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+/* Announcements */
+.bd-header-announcement {
+  background-color: orange;
+}
+
+/* Dark theme tweaking */
+html[data-theme=dark] .sd-card img[src*='.svg'] {
+    filter: invert(0.82) brightness(0.8) contrast(1.2);
+}
+
+/* Main index page overview cards */
+html[data-theme=dark] .sd-card {
+  background-color:var(--pst-color-background);
+}
+
+html[data-theme=dark] .sd-shadow-sm {
+    box-shadow: 0 .1rem 1rem rgba(250, 250, 250, .6) !important
+}
+
+html[data-theme=dark] .sd-card .sd-card-header {
+  background-color:var(--pst-color-background);
+  color: #150458 !important;
+}
+
+html[data-theme=dark] .sd-card .sd-card-footer {
+  background-color:var(--pst-color-background);
+}
+
+html[data-theme=dark] .bd-header-announcement {
+  background-color: red;
+}
+
+html[data-theme=dark] h1 {
+  color: var(--pst-color-primary);
+}
+
+html[data-theme=dark] h3 {
+  color: #0a6774;
+}
+
+.sd-btn-secondary {
+    background-color: var(--matgenix-color) !important;
+    border-color: var(--matgenix-color) !important;
+}
+
+.sd-btn-secondary:hover, .sd-btn-secondary:focus {
+    background-color: var(--matgenix-dark-color) !important;
+    border-color: var(--matgenix-dark-color) !important;
+}

doc/source/api/index.rst

@@ -0,0 +1,9 @@
+.. _api:
+
+#############
+API Reference
+#############
+
+This is the API reference
+
+.. include:: qtoolkit.rst