Docs

docs/api/gui.md

@@ -0,0 +1,3 @@
+# API Documentation for the GUI
+
+::: rimsschemedrawer.gui

docs/api/index.md

@@ -1 +1,53 @@
 # API Documentation
+
+The `RIMSSchemeDrawer` can be run without a GUI.
+Here you find some documentation on how to use the library itself.
+
+## Installation
+
+The package can be installed via `pip`:
+
+```bash
+pip install rimsschemedrawer
+```
+
+This will install the package without the GUI.
+If you want the GUI components as well,
+install the package as:
+
+```bash
+pip install rimsschemedrawer[gui]
+```
+
+## Create a figure
+
+In order to create a figure,
+you need to have an available dictionary that holds the information for a given scheme.
+Let us first look at an example, where a configuration file is available.
+You can find an example file
+[here](https://github.com/RIMS-Code/RIMSSchemeDrawer/blob/main/examples/example_titanium.json).
+
+The following code snippet will create a figure for you that you can save.
+
+```python
+from pathlib import Path
+
+from rimsschemedrawer import Plotter, json_reader
+
+# Load the configuration file
+config_file = Path("path_to_your_config_file.json")
+config = json_reader(config_file)
+
+# Plot the figure
+plotter = Plotter(config)
+fig = plotter.figure  # returns a matplotlib figure
+
+# Save the figure
+outname = Path("path_to_your_output_file.pdf")
+fig.savefig(outname)
+```
+
+Of course, you can also create your own config dictionary.
+To do so, please have a look at the example file given above.
+If you need further examples,
+you can create them by using the GUI and then save the configuration.

docs/api/json_parser.md

@@ -0,0 +1,3 @@
+# JSON parser
+
+::: rimsschemedrawer.json_parser

docs/api/plotter.md

@@ -0,0 +1,3 @@
+# Plotter
+
+::: rimsschemedrawer.plotter

docs/api/utils.md

@@ -0,0 +1,3 @@
+# Utilities
+
+::: rimsschemedrawer.utils

docs/dev.md

@@ -0,0 +1,81 @@
+# Development guide
+
+We welcome new contribution!
+Please feel free to open pull-requests and/or issues.
+If you are not sure what to do,
+file an [issue on GitHub](https://github.com/RIMS-Code/RIMSSchemeDrawer/issues)
+and we can discuss it there.
+
+Contributions do not only have to be in the form of code.
+We also welcome contributions in the form of documentation, etc.!
+
+Below are some guidelines/rough instructions on how this project is set up.
+If you have any questions, please raise them!
+
+## Configuration
+
+The `RIMSSchemeDrawer` package is configured to use
+[`rye`](https://rye-up.com/) for the development environment.
+If you have `rye` installed, clone the repo and then run
+
+```bash
+rye sync --aditional-features
+```
+
+to get the full development environment setup.
+
+## Pre-commit hooks
+
+We use [`pre-commit`](https://pre-commit.com/) hooks in order to ensure
+code formatting and linting prior to committing. To install the hooks, run
+
+```bash
+pre-commit install
+```
+
+!!! note
+    In order for this to work, you must have `pre-commit` itself installed.
+    If you use `rye`, you can simply install it by running
+
+    ```bash
+    rye install pre-commit
+    ```
+
+## Testing
+
+We use `pytest` for testing. To run the tests, simply run
+
+```bash
+rye run test
+```
+
+## Documentation
+
+Please ensure that all features, etc., are documented.
+The documentation is built using `mkdocs` and `mkdocstrings`.
+To check the documentation locally,
+run
+
+```bash
+rye run mkdocs serve
+```
+
+and then open your browser at `http://localhost:8000`.
+You should see the documentation there.
+
+Upon a pull-request,
+the documentation is also created using a readthedocs webhook.
+You can see the documentation by clicking on the appropriate check in the pull-request.
+
+## Formatting and linting
+
+We use [`ruff`](https://astral.sh/ruff) for formatting and linting.
+You can run `ruff` directly from `rye`:
+
+```bash
+rye fmt
+rye lint
+```
+
+This will run the formatter (first line)
+and the linter (second line).

docs/gui.md

@@ -1 +1,119 @@
 # Graphical user interface
+
+## Overview
+
+When starting the program, the user is presented with the following interface (minus the markings).
+
+![Main window](img/gui_overview.png)
+
+The window is divided into several components:
+
+1. The main area to define the laser ionization scheme.
+2. Settings and configurations for how to display the plot. These are pre-filled with some reasonable defaults.
+3. The button to plot and show the figure.
+4. Buttons to load and save configurations.
+5. A button to set the formatting settings back to the default values.
+6. Buttons to get information about the program and to quit the program.
+
+An example of the filled in GUI can be seen here and is discussed further below.
+
+![Example GUI Ti](img/gui_ti_scheme.png)
+
+
+## Resonance ionization scheme
+
+The scheme can be set up in the left hand side of the program.
+The following shows a marked up version of this part:
+
+![Scheme section](img/gui_scheme.png)
+
+The sections are as follows:
+
+1. Unit selection: Please select if you want to enter the transitions in nm or in cm<sup>-1</sup>.
+2. Here you can enter the states / transitions.
+    The units that need to be entered are automatically updated if you change the selection in 1.
+3. In the left column, please give the term symbol of the state that should be displayed.
+    On the right, please enter the transition strength in s<sup>-1</sup>. Note that
+    To display the transition strength in the plot, the according box in the settings (see below) must be checked.
+4. If the ground state manifold contains low-lying states, please check the left box in this section.
+    The state must then be given in cm<sup>-1</sup>.
+    If a transition is forbidden, you can additionally check the "Forbidden?" box.
+5. As you can see for the IP level in 1, the ionization potential is automatically set.
+    We currently include all elements with IPs define in the
+    [NIST Atomic Spectra Database](https://physics.nist.gov/PhysRefData/ASD/levels_form.html).
+    Finally, please select the lasers that were used for this scheme.
+    While this is unimportant for the plot, it is used when submitting a scheme to the online database.
+
+## Settings of the plot
+
+The settings of the plot can be configured on the right-hand side of the program, labeled 2 in the overview image.
+The following settings from top to bottom in the left column are available.
+
+1. Width and height of the figure. This is set in inches, however, the actual units are fairly unimportant.
+2. Font size of the title (if set).
+3. Font size of the axes.
+4. Font size of the axes labels.
+5. Headspace in cm<sup>-1</sup>. This is the space above the IP that will be added.
+    This is one of the most frequent values changed in the settings.
+    For example, you might want to add additional space in order to display all labels nicely within the plot.
+6. Width of the arrow in arbitrary units. Mainly needs to be changed if the figure size is modified.
+7. Arrow head width in arbitrary units. Mainly needs to be changed if the figure size is modified.
+8. Precision of the wavelength: How many digits should be displayed for the wavelengths?
+9. Precision of the levels: How many digits should be displayed for the levels?
+10. Where should the IP be labeled: on top or on the bottom of the IP line?
+11. How do you want to show forbidden transitions? Cross them out ("x-out") or don't show them at all ("Don't show")?
+
+In the right column, the following options are available:
+
+1. Plot title: Here you can enter an optional title for the plot.
+2. Transition strengths? Checkbox to display the transition strengths in the plot.
+3. Line breaks? Checkbox to show line breaks between the levels and the term symbols.
+    This can be useful if you want a narrow figure or higher level precision.
+4. Show cm<sup>-1</sup> axis labels? If unchecked, the left axis labels will disappear.
+5. Show eV axis labels? If unchecked, the right axis labels will disappear.
+6. Plot dark mode? If checked, the plot will be displayed in dark mode.
+    This can be useful, e.g., if you create slides with a dark background.
+
+!!! note
+    The filled GUI example image above shows a reasonable setup for a Ti resonance ionization scheme (plot shown below).
+    Note especially the setup for the low-lying states and the term symbols that were entered.
+
+
+!!! note "Show axis labels"
+    The "Show axis labels" as described above can be useful in case you need to combine multiple schemes into one figure.
+    In this case, create multiple figures with the same figure height.
+    Then, calculate the headspace for each figure, such that the cm<sup>-1</sup> of the maximum height align in each figure.
+    The total height of the figure will always be IP level + headspace.
+    Finally, save the figure (see below), e.g., as an `svg` file and combine the figures with a vector graphics editor.
+
+## Plotting
+
+Once the scheme is filled out, hit the "Plot" button in order to display a figure.
+A window will open with the figure.
+Here's an example:
+
+![Example Titanium](img/plot_window.png)
+
+This figure is for a Ti resonance ionization scheme,
+taken from [Trappitsch et al. (2018)](https://doi.org/10.1039/C8JA00269J).
+The setup of the GUI to create this scheme can be found above.
+
+To save this figure, you can use the [floppy disk](https://en.wikipedia.org/wiki/Floppy_disk)
+icon in the toolbar of the figure window.
+The available formats can be found [here](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.savefig.html).
+Recommended saving formats are `png` for pixel graphics and `svg` or `pdf` for vector graphics.
+
+## Saving and loading configurations
+
+If you want to save a given configuration, you can use the "Save Config" button.
+The data will be saved as a `json` file.
+You can open a saved file with any text editor and have a look,
+but please note that bad things can happen if you change the file right there,
+unless of course you know what you're doing.
+The file should be fairly self-explanatory.
+
+To load a given configuration, you can use the "Load Config" button.
+This will open a file dialog where you can select the file to load.
+
+The configuration file for the example titanium scheme shown above can be found
+[here](https://github.com/RIMS-Code/RIMSSchemeDrawer/blob/main/examples/example_titanium.json).

examples/example_titanium.json

@@ -1,40 +1,66 @@
 {
     "scheme": {
-        "gs_level": "0",
+        "element": "Ti",
+        "gs_level": "0.0",
         "gs_term": "3F2",
-        "ip_level": "55074",
         "ip_term": "",
+        "lasers": "Ti:Sa",
+        "step_forbidden0": false,
+        "step_forbidden1": false,
+        "step_forbidden2": false,
+        "step_forbidden3": false,
+        "step_forbidden4": false,
+        "step_forbidden5": false,
+        "step_forbidden6": false,
         "step_level0": "170.15",
         "step_level1": "386.88",
         "step_level2": "21469.5",
         "step_level3": "45498.85",
         "step_level4": "56844.45",
+        "step_level5": "",
+        "step_level6": "",
         "step_lowlying0": true,
         "step_lowlying1": true,
         "step_lowlying2": false,
         "step_lowlying3": false,
         "step_lowlying4": false,
+        "step_lowlying5": false,
+        "step_lowlying6": false,
         "step_term0": "3F3",
         "step_term1": "3F4",
         "step_term2": "3G3",
         "step_term3": "3G4",
         "step_term4": "",
+        "step_term5": "",
+        "step_term6": "",
+        "trans_strength0": "",
+        "trans_strength1": "",
+        "trans_strength2": "",
+        "trans_strength3": "",
+        "trans_strength4": "",
+        "trans_strength5": "",
+        "trans_strength6": "",
         "unit": "cm<sup>-1</sup>"
     },
     "settings": {
         "arrow_head_width": "0.6",
         "arrow_width": "0.2",
-        "fig_height": "8",
-        "fig_width": "5",
-        "fs_axes": "12",
-        "fs_axes_labels": "14",
-        "fs_labels": "12",
-        "fs_title": "14",
-        "headspace": "2700",
+        "fig_height": "8.0",
+        "fig_width": "5.0",
+        "fs_axes": "12.0",
+        "fs_axes_labels": "14.0",
+        "fs_labels": "12.0",
+        "fs_title": "14.0",
+        "headspace": "2700.0",
         "ip_label_pos": "Top",
         "line_breaks": false,
+        "plot_darkmode": false,
         "plot_title": "",
         "prec_level": "0",
-        "prec_wavelength": "3"
+        "prec_wavelength": "3",
+        "show_cm-1_axis": true,
+        "show_eV_axis": true,
+        "show_forbidden_transitions": "x-out",
+        "show_transition_strength": true
     }
-}
+}

mkdocs.yml

@@ -39,10 +39,21 @@ markdown_extensions:
 
 plugins:
   - search
-
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: sphinx
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
 nav:
   - Home: index.md
   - Installation: install.md
   - GUI: gui.md
+  - Development: dev.md
   - API:
       - Overview: api/index.md
+      - Plotter: api/plotter.md
+      - JSON Parser: api/json_parser.md
+      - Utilities: api/utils.md
+      - GUI: api/gui.md

pyproject.toml

@@ -24,6 +24,7 @@ gui = [
 docs = [
     "mkdocs>=1.5.3",
     "mkdocs-material>=9.5.12",
+    "mkdocstrings[python]>=0.24.1",
 ]
 
 [project.urls]