Start docs (#16)

* start the documentation

* add readthedocs yaml

.readthedocs.yaml

@@ -0,0 +1,20 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+# install package via pip
+python:
+   install:
+       - requirements: requirements.lock

docs/api/index.md

@@ -0,0 +1 @@
+# API Documentation

docs/gui.md

@@ -0,0 +1 @@
+# Graphical user interface

docs/index.md

@@ -0,0 +1,35 @@
+# RIMSSchemeDrawer Documentation
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Rye](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/mitsuhiko/rye/main/artwork/badge.json)](https://rye-up.com)
+[![PyPI](https://img.shields.io/pypi/v/rimsschemedrawer)](https://pypi.org/project/rimsschemedrawer/)
+[![Documentation Status](https://readthedocs.org/projects/rimsschemedrawer/badge/?version=latest)](https://rimsschemedrawer.readthedocs.io/en/latest/?badge=latest)
+[![codecov](https://codecov.io/gh/RIMS-Code/RIMSSchemeDrawer/graph/badge.svg?token=TUUIKGLGGD)](https://codecov.io/gh/RIMS-Code/RIMSSchemeDrawer)
+[![tests](https://github.com/RIMS-Code/RIMSSchemeDrawer/actions/workflows/package_testing.yml/badge.svg)](https://github.com/RIMS-Code/RIMSSchemeDrawer/actions/workflows/package_testing.yml)
+
+## Welcome!
+
+As the name implies,
+the `RIMSSchemeDrawer` is a tool to draw resonance ionization schemes.
+The goal of this package is to create a publication-ready figure.
+
+The easiest way to use the software is via a graphical user interface (GUI).
+However, the software can also be used as a library.
+Please see the [API documentation](api/index.md) for more information.
+
+## Next steps
+
+Please check out the [installation guide](install.md) to get started.
+While the GUI is fairly self-explanatory
+and includes many tool-tips to help you navigate,
+you might also want to check out the [how-to guide](gui.md).
+
+## Issues/Enhancements
+
+If you run into any problems with the software
+or have ideas for enhancements,
+please raise an issue [here on GitHub](https://github.com/RIMS-Code/RIMSSchemeDrawer/issues).
+
+## License
+
+This software is licensed under the [MIT license](https://github.com/RIMS-Code/RIMSSchemeDrawer/blob/main/LICENSE).

docs/install.md

@@ -0,0 +1,37 @@
+# Installation
+
+We provide two main ways of installation,
+either directly via `pip` or using the fully packaged installer
+that can be found in our [releases](https://github.com/RIMS-Code/RIMSSchemeDrawer/releases).
+
+!!! note "Fully packaged installer"
+    As of version `v3`, the fully packaged release is created with
+    [`PyApp`](https://ofek.dev/pyapp/latest/).
+    This has various advantages for our own workflow,
+    however, requires that you have an internet connection when first starting the software.
+    `PyApp` will create a virtual environment for you and install the software there,
+    however, will need to download all dependencies in the process.
+
+## Installation via `pip`
+
+We highly recommend using [`pipx`](https://pipxproject.github.io/pipx/)
+to install the software.
+To do so,
+simply run the following command in your terminal:
+
+```bash
+pipx install rimsschemedrawer[gui]
+```
+
+This will install the software and all its dependencies in an isolated environment.
+You can then run the software by simply typing `rimsschemedrawer` in your terminal.
+
+## Installation via the fully packaged installer
+
+Download the latest release from [here](https://github.com/RIMS-Code/RIMSSchemeDrawer/releases)
+by choosing the appropriate file for your operating system.
+After downloading,
+simply run the file.
+
+!!! note
+    The files are not signed and you might get a warning from your operating system.

mkdocs.yml

@@ -0,0 +1,48 @@
+site_name: RIMSSchemeDrawer
+
+theme:
+  name: material
+  features:
+    - content.code.copy
+    - content.code.select
+    - navigation.footer
+  palette:
+    # Palette toggle for dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+    # Palette toggle for light mode
+    - scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+site_url: https://rimsschemedrawer.readthedocs.io
+repo_url: https://github.com/RIMS-Code/RIMSSchemeDrawer
+site_author: Reto Trappitsch
+
+markdown_extensions:
+  - admonition
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+
+
+plugins:
+  - search
+
+nav:
+  - Home: index.md
+  - Installation: install.md
+  - GUI: gui.md
+  - API:
+      - Overview: api/index.md

pyproject.toml

@@ -21,6 +21,10 @@ gui = [
     "PyQt6>=6.6.1",
     "qtpy>=2.4.1",
 ]
+docs = [
+    "mkdocs>=1.5.3",
+    "mkdocs-material>=9.5.12",
+]
 
 [project.urls]
 Homepage = "https://github.com/RIMS-Code/RIMSSchemeDrawer"

requirements-dev.lock

@@ -10,10 +10,16 @@
 -e file:.
 attrs==23.2.0
     # via hypothesis
+babel==2.14.0
+    # via mkdocs-material
 certifi==2024.2.2
     # via requests
 charset-normalizer==3.3.2
     # via requests
+click==8.1.7
+    # via mkdocs
+colorama==0.4.6
+    # via mkdocs-material
 contourpy==1.2.0
     # via matplotlib
 coverage==7.4.3
@@ -22,27 +28,59 @@ cycler==0.12.1
     # via matplotlib
 fonttools==4.49.0
     # via matplotlib
+ghp-import==2.1.0
+    # via mkdocs
 hypothesis==6.98.13
 idna==3.6
     # via requests
 iniconfig==2.0.0
     # via pytest
+jinja2==3.1.3
+    # via mkdocs
+    # via mkdocs-material
 kiwisolver==1.4.5
     # via matplotlib
+markdown==3.5.2
+    # via mkdocs
+    # via mkdocs-material
+    # via pymdown-extensions
+markupsafe==2.1.5
+    # via jinja2
+    # via mkdocs
 matplotlib==3.8.3
     # via rimsschemedrawer
+mergedeep==1.3.4
+    # via mkdocs
+mkdocs==1.5.3
+    # via mkdocs-material
+    # via rimsschemedrawer
+mkdocs-material==9.5.12
+    # via rimsschemedrawer
+mkdocs-material-extensions==1.3.1
+    # via mkdocs-material
 numpy==1.26.4
     # via contourpy
     # via matplotlib
     # via rimsschemedrawer
 packaging==23.2
     # via matplotlib
+    # via mkdocs
     # via pytest
     # via qtpy
+paginate==0.5.6
+    # via mkdocs-material
+pathspec==0.12.1
+    # via mkdocs
 pillow==10.2.0
     # via matplotlib
+platformdirs==4.2.0
+    # via mkdocs
 pluggy==1.4.0
     # via pytest
+pygments==2.17.2
+    # via mkdocs-material
+pymdown-extensions==10.7
+    # via mkdocs-material
 pyparsing==3.1.1
     # via matplotlib
 pyqt6==6.6.1
@@ -55,13 +93,25 @@ pytest==8.0.2
     # via pytest-cov
 pytest-cov==4.1.0
 python-dateutil==2.8.2
+    # via ghp-import
     # via matplotlib
+pyyaml==6.0.1
+    # via mkdocs
+    # via pymdown-extensions
+    # via pyyaml-env-tag
+pyyaml-env-tag==0.1
+    # via mkdocs
 qtpy==2.4.1
     # via rimsschemedrawer
+regex==2023.12.25
+    # via mkdocs-material
 requests==2.31.0
+    # via mkdocs-material
 six==1.16.0
     # via python-dateutil
 sortedcontainers==2.4.0
     # via hypothesis
 urllib3==2.2.1
     # via requests
+watchdog==4.0.0
+    # via mkdocs

requirements.lock

@@ -8,25 +8,69 @@
 #   with-sources: false
 
 -e file:.
+babel==2.14.0
+    # via mkdocs-material
+certifi==2024.2.2
+    # via requests
+charset-normalizer==3.3.2
+    # via requests
+click==8.1.7
+    # via mkdocs
+colorama==0.4.6
+    # via mkdocs-material
 contourpy==1.2.0
     # via matplotlib
 cycler==0.12.1
     # via matplotlib
 fonttools==4.49.0
     # via matplotlib
+ghp-import==2.1.0
+    # via mkdocs
+idna==3.6
+    # via requests
+jinja2==3.1.3
+    # via mkdocs
+    # via mkdocs-material
 kiwisolver==1.4.5
     # via matplotlib
+markdown==3.5.2
+    # via mkdocs
+    # via mkdocs-material
+    # via pymdown-extensions
+markupsafe==2.1.5
+    # via jinja2
+    # via mkdocs
 matplotlib==3.8.3
     # via rimsschemedrawer
+mergedeep==1.3.4
+    # via mkdocs
+mkdocs==1.5.3
+    # via mkdocs-material
+    # via rimsschemedrawer
+mkdocs-material==9.5.12
+    # via rimsschemedrawer
+mkdocs-material-extensions==1.3.1
+    # via mkdocs-material
 numpy==1.26.4
     # via contourpy
     # via matplotlib
     # via rimsschemedrawer
 packaging==23.2
     # via matplotlib
+    # via mkdocs
     # via qtpy
+paginate==0.5.6
+    # via mkdocs-material
+pathspec==0.12.1
+    # via mkdocs
 pillow==10.2.0
     # via matplotlib
+platformdirs==4.2.0
+    # via mkdocs
+pygments==2.17.2
+    # via mkdocs-material
+pymdown-extensions==10.7
+    # via mkdocs-material
 pyparsing==3.1.1
     # via matplotlib
 pyqt6==6.6.1
@@ -36,8 +80,23 @@ pyqt6-qt6==6.6.2
 pyqt6-sip==13.6.0
     # via pyqt6
 python-dateutil==2.8.2
+    # via ghp-import
     # via matplotlib
+pyyaml==6.0.1
+    # via mkdocs
+    # via pymdown-extensions
+    # via pyyaml-env-tag
+pyyaml-env-tag==0.1
+    # via mkdocs
 qtpy==2.4.1
     # via rimsschemedrawer
+regex==2023.12.25
+    # via mkdocs-material
+requests==2.31.0
+    # via mkdocs-material
 six==1.16.0
     # via python-dateutil
+urllib3==2.2.1
+    # via requests
+watchdog==4.0.0
+    # via mkdocs