Improve documentation

.gitignore

@@ -2,12 +2,10 @@ __pycache__
 # do not track doc files that are automatically build
 doc/build
 doc/source/*.rst
+doc/source/*.md
 
 # but keep index.rst
 !doc/source/index.rst
-!doc/source/intro.rst
-!doc/source/tutorials.rst
-!doc/source/architecture.rst
 
 # C extensions
 *.so

CONTRIBUTING.md

@@ -32,9 +32,11 @@ have to solve them yourself.
 
 ### 1. Install QUEENS in developer mode
 Install QUEENS as described in the [README.md](README.md) and run:
+<!---installation_develop marker, do not remove this comment-->
 ```
 pip install -e .[develop]
 ```
+<!---installation_develop marker, do not remove this comment-->
 
 ### 2. Configure our git-hooks
 To help you write style-compliant code, we use the [pre-commit](https://pre-commit.com/) package to manage all our git
@@ -54,7 +56,7 @@ The code checks are conducted with [Pylint](https://pylint.org/),
 Compliance with [Google style docstrings](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings)
 is checked with [ruff](https://github.com/astral-sh/ruff).
 Complete and meaningful docstrings are required as they are used to generate the
-[documentation](#reading-and-writing-documentation).
+[documentation](#book-documentation).
 
 #### Commit messages
 Please provide meaningful commit messages based on the

README.md

@@ -1,10 +1,11 @@
-
 <div align="center">
+
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/queens-py/queens-design/main/logo/queens_logo_night.svg">
-  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/queens-py/queens-design/main/logo/queens_logo_day.svg">
-  <img alt="QUEENS logo" src="https://raw.githubusercontent.com/queens-py/queens-design/main/logo/queens_logo_night.svg" width="300">
+  <source media="(prefers-color-scheme: dark)" srcset="doc/source/images/queens_logo_night.svg">
+  <source media="(prefers-color-scheme: light)" srcset="doc/source/images/queens_logo_day.svg">
+  <img alt="QUEENS logo" src="doc/source/images/queens_logo_night.svg" width="300">
 </picture>
+
 </div>
 
 <div align="center">
@@ -24,8 +25,11 @@
 
 </div>
 
+<!---description marker, do not remove this comment-->
 QUEENS (**Q**uantification of **U**ncertain **E**ffects in **En**gineering **S**ystems) is a Python framework for solver-independent multi-query analyses of large-scale computational models.
+<!---description marker, do not remove this comment-->
 
+<!---capabilities marker, do not remove this comment-->
 :chart_with_upwards_trend: **QUEENS** offers a large collection of cutting-edge algorithms for deterministic and probabilistic analyses such as:
 * parameter studies and identification
 * sensitivity analysis
@@ -38,17 +42,22 @@ QUEENS (**Q**uantification of **U**ncertain **E**ffects in **En**gineering **S**
 * robust data, resource, and error management
 * easy switching between analysis types
 * smooth scaling from laptop to HPC cluster
+<!---capabilities marker, do not remove this comment-->
 
 ## :rocket: Getting started
 
+<!---prerequisites marker, do not remove this comment-->
 >**Prerequisites**: Unix system and environment management system (we recommend [miniforge](https://conda-forge.org/download/))
+<!---prerequisites marker, do not remove this comment-->
 
+<!---installation marker, do not remove this comment-->
 Clone the QUEENS repository to your local machine. Navigate to its base directory, then:
 ```
 conda env create
 conda activate queens
 pip install -e .
 ```
+<!---installation marker, do not remove this comment-->
 
 ## :crown: Workflow example
 
@@ -97,7 +106,7 @@ if __name__ == "__main__":
 <!---example marker, do not remove this comment-->
 
 <div align="center">
-<img src="readme_images/monte_carlo_uq.png" alt="QUEENS logo" width="500"/>
+<img src="doc/source/images/monte_carlo_uq.png" alt="QUEENS example" width="500"/>
 </div>
 
 ## :busts_in_silhouette: Contributing
@@ -107,6 +116,7 @@ Your contributions are welcome! Please follow our [contributing guidelines](http
 ## :page_with_curl: How to cite
 If you use QUEENS in your work, please cite the relevant method papers and
 
+<!---citation marker, do not remove this comment-->
 ```bib
 @misc{queens,
   author       = {QUEENS},
@@ -115,6 +125,9 @@ If you use QUEENS in your work, please cite the relevant method papers and
   howpublished = {\url{https://www.queens-py.org}}
 }
 ```
+<!---citation marker, do not remove this comment-->
 
 ## :woman_judge: License
+<!---license marker, do not remove this comment-->
 Licensed under GNU LGPL-3.0 (or later). See [LICENSE](LICENSE).
+<!---license marker, do not remove this comment-->

dev-requirements.in

@@ -20,3 +20,4 @@ commitizen>=3.12.0
 docformatter>=1.5.1
 yamllint>=1.19.0
 ruff
+myst-parser

dev-requirements.txt

@@ -1,5 +1,5 @@
 #
-# This file is autogenerated by pip-compile with Python 3.11
+# This file is autogenerated by pip-compile with Python 3.10
 # by the following command:
 #
 #    pip-compile --output-file=dev-requirements.txt dev-requirements.in
@@ -62,6 +62,7 @@ docformatter==1.7.5
     # via -r dev-requirements.in
 docutils==0.21.2
     # via
+    #   myst-parser
     #   nbsphinx
     #   pydata-sphinx-theme
     #   sphinx
@@ -79,6 +80,10 @@ idna==3.10
     #   requests
 imagesize==1.4.1
     # via sphinx
+importlib-metadata==6.11.0
+    # via
+    #   -c requirements.txt
+    #   build
 isort==5.13.2
     # via
     #   -r dev-requirements.in
@@ -87,6 +92,7 @@ jinja2==3.1.4
     # via
     #   -c requirements.txt
     #   commitizen
+    #   myst-parser
     #   nbconvert
     #   nbsphinx
     #   sphinx
@@ -108,15 +114,28 @@ liccheck==0.9.2
     # via -r dev-requirements.in
 licenseheaders==0.8.8
     # via -r dev-requirements.in
+markdown-it-py==3.0.0
+    # via
+    #   -c requirements.txt
+    #   mdit-py-plugins
+    #   myst-parser
 markupsafe==3.0.2
     # via
     #   -c requirements.txt
     #   jinja2
     #   nbconvert
 mccabe==0.7.0
     # via pylint
+mdit-py-plugins==0.4.2
+    # via myst-parser
+mdurl==0.1.2
+    # via
+    #   -c requirements.txt
+    #   markdown-it-py
 mistune==3.0.2
     # via nbconvert
+myst-parser==4.0.0
+    # via -r dev-requirements.in
 nbclient==0.10.0
     # via nbconvert
 nbconvert==7.16.4
@@ -188,6 +207,7 @@ pyyaml==6.0.2
     # via
     #   -c requirements.txt
     #   commitizen
+    #   myst-parser
     #   pre-commit
     #   yamllint
 pyzmq==26.2.0
@@ -228,6 +248,7 @@ soupsieve==2.6
 sphinx==8.1.3
     # via
     #   -r dev-requirements.in
+    #   myst-parser
     #   nbsphinx
     #   pydata-sphinx-theme
 sphinxcontrib-applehelp==2.0.0
@@ -250,6 +271,14 @@ tinycss2==1.4.0
     # via nbconvert
 toml==0.10.2
     # via liccheck
+tomli==2.0.2
+    # via
+    #   -c requirements.txt
+    #   build
+    #   pip-tools
+    #   pre-commit-hooks
+    #   pylint
+    #   sphinx
 tomlkit==0.13.2
     # via
     #   commitizen
@@ -269,6 +298,7 @@ traitlets==5.14.3
 typing-extensions==4.12.2
     # via
     #   -c requirements.txt
+    #   astroid
     #   pydata-sphinx-theme
 untokenize==0.1.1
     # via docformatter
@@ -290,6 +320,10 @@ wheel==0.44.0
     #   pip-tools
 yamllint==1.35.1
     # via -r dev-requirements.in
+zipp==3.20.2
+    # via
+    #   -c requirements.txt
+    #   importlib-metadata
 
 # The following packages are considered to be unsafe in a requirements file:
 # pip