mEngstroem · mEngstroem · Apr 3, 2025 · Apr 2, 2025 · Apr 2, 2025 · Apr 2, 2025
diff --git a/.github/workflows/documentation-build.yml b/.github/workflows/documentation-build.yml
@@ -0,0 +1,51 @@
+# This pipeline
+# - builds developer documentation
+# - pushes documentation to gh-pages branch of the same repository
+#
+# Deployment is handled by pages-build-deployment bot
+#
+# For more information see: https://docs.github.com/en/pages/getting-started-with-github-pages
+
+name: Build Documentation and Push to gh-pages Branch
+
+# Controls when the workflow will run
+on:
+  # Triggers the workflow on tag creation
+  push:
+    tags:
+      - 'v*'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job called "build"
+  build_documentation:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@master
+      with:
+        fetch-depth: 0 # otherwise, you will failed to push refs to dest repo
+    - name: Upgrade pip
+      run: |
+        python -m pip install --upgrade pip
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.11
+    - name: Install Pandoc, repo and dependencies
+      run: |
+        sudo apt install pandoc
+        pip install . '.[docs]'
+    - name: Build and Commit
+      uses: sphinx-notes/pages@master
+      with:
+        install_requirements: true
+        documentation_path: docs/src
+    - name: Push changes
+      uses: ad-m/github-push-action@master
+      continue-on-error: true
+      with:
+        branch: gh-pages
diff --git a/.gitignore b/.gitignore
@@ -46,7 +46,7 @@ settings.ini*
 .ci/
 .idea/
 .vscode/
-ci/
+
 
 #Snap
 *.snap
diff --git a/docs/Makefile b/docs/Makefile
@@ -5,7 +5,7 @@
 SPHINXOPTS    =
 SPHINXBUILD   = python -msphinx
 SPHINXPROJ    = EasyReflectometry
-SOURCEDIR     = .
+SOURCEDIR     = ./src
 BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".

diff --git a/docs/adrs.rst b/docs/adrs.rst
diff --git a/docs/make.bat b/docs/make.bat
@@ -7,7 +7,7 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=python -msphinx
 )
-set SOURCEDIR=.
+set SOURCEDIR=./src
 set BUILDDIR=_build
 set SPHINXPROJ=orsopy
 

diff --git a/docs/_static/favicon.ico → docs/src/_static/favicon.ico b/docs/_static/favicon.ico → docs/src/_static/favicon.ico
diff --git a/docs/adrs.md → docs/src/adrs.md b/docs/adrs.md → docs/src/adrs.md
diff --git a/docs/adrs/adr0001.md → docs/src/adrs/adr0001.md b/docs/adrs/adr0001.md → docs/src/adrs/adr0001.md
diff --git a/docs/adrs/adr0001.rst → docs/src/adrs/adr0001.rst b/docs/adrs/adr0001.rst → docs/src/adrs/adr0001.rst
diff --git a/docs/adrs/adr0002.rst → docs/src/adrs/adr0002.rst b/docs/adrs/adr0002.rst → docs/src/adrs/adr0002.rst
diff --git a/docs/adrs/adr0003.rst → docs/src/adrs/adr0003.rst b/docs/adrs/adr0003.rst → docs/src/adrs/adr0003.rst
diff --git a/docs/build.md → docs/src/build.md b/docs/build.md → docs/src/build.md
@@ -18,13 +18,13 @@ $ cd ../
 Then, to that you are working with your local version of `EasyReflectometryLib`, you want to change line 35 of the `EasyReflectometryApp` `pyproject.toml` file from
 
 ```toml
-'EasyReflectometryLib @ git+https://github.com/easyScience/EasyReflectometryLib.git@develop',
+'EasyReflectometryLib @ git+https://github.com/easyScience/EasyReflectometryLib.git@develop'
 ```
 
 to use the directory where you have cloned `EasyReflectometryLib`, i.e.
 
 ```toml
-'EasyReflectometryLib @ file:///path/to/EasyReflectometryLib',
+'EasyReflectometryLib @ file:///path/to/EasyReflectometryLib'
 ```
 
 With this modification in place, you should then be able to install `EasyReflectometryApp`

diff --git a/docs/ci.md → docs/src/ci.md b/docs/ci.md → docs/src/ci.md
diff --git a/docs/ci/build.md → docs/src/ci/build.md b/docs/ci/build.md → docs/src/ci/build.md
@@ -4,7 +4,7 @@ The aim of building the application and library is to create an accessible, eith
 
 ## `EasyReflectometryLib`
 
-Based on [ADR0002](./adrs/adr0002), the only expected method of installation for the Python library is via PyPI (or some other `pip` compatible approach). 
+Based on [ADR0002](./../adrs/adr0002.rst), the only expected method of installation for the Python library is via PyPI (or some other `pip` compatible approach). 
 Therefore, the building of `EasyReflectometryLib` is achieved through relatively standard Github actions for pushing built Python modules to PyPI.
 This is achieved though common approaches, discussed in [this PyPA documentation](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/), specifically the Github action defined in the [`python-publish.yml` workflow](https://github.com/easyScience/EasyReflectometryLib/blob/main/.github/workflows/python-publish.yml). 
 
@@ -24,7 +24,7 @@ This action performs the following steps:
 2. A series of environment variables are set, mostly related to the git state at the time. These are used in the built app to give extra information regarding provenence. 
 3. The application bundle is then created and the installers are produced using [PyInstaller](https://pyinstaller.org/en/stable/). 
 4. These are installed on the build machines and the application is launched (and then quit), to test if the build is at least in part successful. 
-5. The installers are then made available for [testing](#testing) as Github artifacts of the action. 
+5. The installers are then made available for :ref:`testing` as Github artifacts of the action. 
 6. If the build is happening on the `master` branch, the installer is also added to a release.
 
 ### Testing

diff --git a/docs/conf.py → docs/src/conf.py b/docs/conf.py → docs/src/conf.py
@@ -53,9 +53,9 @@
 # the built documents.
 #
 # The short X.Y version.
-version = '0.0.1' 
+version = '1.0.0' 
 # The full version, including alpha/beta/rc tags.
-release = '0.0.1'
+release = '1.0.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/docs/index.md → docs/src/index.md b/docs/index.md → docs/src/index.md
@@ -9,7 +9,7 @@ Therefore, this will be where information for developers will be found, such as
 ---
 hidden: True
 --- 
-
+tutorial
 build
 adrs
 ci

diff --git a/docs/tutorials/getting-started.md → docs/src/tutorial.md b/docs/tutorials/getting-started.md → docs/src/tutorial.md
@@ -5,7 +5,7 @@ Version: 1.0.0
 ## Home page
 When opening up the EasyRecletometryApp you are presented with the **Home** page.  
 
-<img src='./_images/home.png' width='800px'></img>
+<img src='./tutorials/_images/home.png' width='800px'></img>
 
 - **A**: Starts your project.
 - **B**: Pop-up window with source information.
@@ -15,7 +15,7 @@ When opening up the EasyRecletometryApp you are presented with the **Home** page
 
 Pressing **A** will direct you to the **Project** page.  
 
-<img src='./_images/project.png' width='800px'></img>
+<img src='./tutorials/_images/project.png' width='800px'></img>
 
 - **1**: Create a new project as a folder containing experiments and a JSON file for settings.
    - New projects need a name, description and set the save location.
@@ -30,8 +30,20 @@ This project is used going forward to explain the app.
 ## Save and settings
 When a project is started two further buttons is visualised, and settings is the opposite corner of those.
 
-<img src='./_images/save_setting.png' width='800px'></img>
+<img src='./tutorials/_images/save_setting.png' width='800px'></img>
 
 - **A**: Save project.
 - **B**: Reset to start.
 - **C**: Setting, is further explained in settings.
+
+```{toctree}
+---
+maxdepth: 1
+---
+
+tutorials/model_def.md
+tutorials/load_data.md
+tutorials/simple_fitting.md
+tutorials/settings.md
+
+```
diff --git a/docs/tutorials/_images/anal_adv.png → docs/src/tutorials/_images/anal_adv.png b/docs/tutorials/_images/anal_adv.png → docs/src/tutorials/_images/anal_adv.png
diff --git a/docs/tutorials/_images/anal_bsc.png → docs/src/tutorials/_images/anal_bsc.png b/docs/tutorials/_images/anal_bsc.png → docs/src/tutorials/_images/anal_bsc.png
diff --git a/docs/tutorials/_images/exp_data.png → docs/src/tutorials/_images/exp_data.png b/docs/tutorials/_images/exp_data.png → docs/src/tutorials/_images/exp_data.png
diff --git a/docs/tutorials/_images/exp_load.png → docs/src/tutorials/_images/exp_load.png b/docs/tutorials/_images/exp_load.png → docs/src/tutorials/_images/exp_load.png
diff --git a/docs/tutorials/_images/home.png → docs/src/tutorials/_images/home.png b/docs/tutorials/_images/home.png → docs/src/tutorials/_images/home.png
diff --git a/docs/tutorials/_images/polymer_film.png → docs/src/tutorials/_images/polymer_film.png b/docs/tutorials/_images/polymer_film.png → docs/src/tutorials/_images/polymer_film.png
diff --git a/docs/tutorials/_images/polymer_film.svg → docs/src/tutorials/_images/polymer_film.svg b/docs/tutorials/_images/polymer_film.svg → docs/src/tutorials/_images/polymer_film.svg
diff --git a/docs/tutorials/_images/project.png → docs/src/tutorials/_images/project.png b/docs/tutorials/_images/project.png → docs/src/tutorials/_images/project.png
diff --git a/docs/tutorials/_images/sample_adv.png → docs/src/tutorials/_images/sample_adv.png b/docs/tutorials/_images/sample_adv.png → docs/src/tutorials/_images/sample_adv.png
diff --git a/docs/tutorials/_images/sample_layer.png → docs/src/tutorials/_images/sample_layer.png b/docs/tutorials/_images/sample_layer.png → docs/src/tutorials/_images/sample_layer.png
diff --git a/docs/tutorials/_images/sample_material.png → ...src/tutorials/_images/sample_material.png b/docs/tutorials/_images/sample_material.png → ...src/tutorials/_images/sample_material.png
diff --git a/docs/tutorials/_images/sample_model.png → docs/src/tutorials/_images/sample_model.png b/docs/tutorials/_images/sample_model.png → docs/src/tutorials/_images/sample_model.png
diff --git a/docs/tutorials/_images/sample_overview.png → ...src/tutorials/_images/sample_overview.png b/docs/tutorials/_images/sample_overview.png → ...src/tutorials/_images/sample_overview.png
diff --git a/docs/tutorials/_images/save_setting.png → docs/src/tutorials/_images/save_setting.png b/docs/tutorials/_images/save_setting.png → docs/src/tutorials/_images/save_setting.png
diff --git a/docs/tutorials/_images/setting_overview.png → ...rc/tutorials/_images/setting_overview.png b/docs/tutorials/_images/setting_overview.png → ...rc/tutorials/_images/setting_overview.png
diff --git a/docs/tutorials/data/load_data.md → docs/src/tutorials/load_data.md b/docs/tutorials/data/load_data.md → docs/src/tutorials/load_data.md
@@ -3,14 +3,14 @@
 Experimental data must be **.dat**, **.txt**, or **.ort** to be loaded into the EasyReflectometryApp.  
 Data is loaded in the `Experimental` page, by pressing the `Import experimental data`.
 
-<img src='./../_images/exp_load.png' width='800px'></img>
+![Loading data](./_images/exp_load.png)
 
 - **A**: Open your file manager to load data in the mentioned format.
 
 ## Instrumental parameters  
 When data is loaded, it is possible to change instrumental parameters that affect the data.
 
-<img src='./../_images/exp_data.png' width='800px'></img>
+![Setting experimental parameters](./_images/exp_data.png)
 
 - **A**: Scale the data by the given value.
 - **B**: Set the level where data merges into the experimental background.

diff --git a/docs/tutorials/models/model-def.md → docs/src/tutorials/model_def.md b/docs/tutorials/models/model-def.md → docs/src/tutorials/model_def.md
@@ -3,7 +3,7 @@ When a project is initialised it is then possible to define material and set the
 
 Let us first look at the general layout of the `Model` page, which is split up into two parts, the main window showing the graphs and the sidebar being the control panel for variables and data.
 
-<img src='./../_images/sample_overview.png' width='800px'></img>
+![Model overview](./_images/sample_overview.png)
 
 - **A**: Graph change between the Reflectivity- and Scattering Length Density (SLD) curve.
 - **B**: Graph control of ledger, visible coordinates on hower, zoom and pan control, and reset.
@@ -14,7 +14,7 @@ Let us first look at the general layout of the `Model` page, which is split up i
 To construct a model in the app, first, you add the materials that will compose the layers in `Material Editor`.  
 The materials are added by the real and imaginary components of the scattering length density (in units of 10<sup>-6</sup>Å<sup>-2</sup>) and given a name for the material.  
 
-<img src='./../_images/sample_material.png' width='800px'></img>
+![Material editor](./_images/sample_material.png)
 
 - **A**: For adding more material.
 - **B**: Duplicating the last clicked material.
@@ -23,7 +23,7 @@ The materials are added by the real and imaginary components of the scattering l
 ### Model creation and editing
 For creating new models, the `Models selector` tab is used, and then for setting the assemblies in the model the `Model editor` is used.  
 
-<img src='./../_images/sample_model.png' width='800px'></img>
+![Model creation](./_images/sample_model.png)
 
 - **A**: Renaming model.
 - **B**: Removing the specific model.
@@ -37,7 +37,7 @@ For creating new models, the `Models selector` tab is used, and then for setting
 Then for editing the assemblies in the model, the `Layer editor` is used.  
 By clicking an assembly, the `Layer editor` is specified and changes can be made to that assembly.
 
-<img src='./../_images/sample_layer.png' width='800px'></img>
+![Layer editor](./_images/sample_layer.png)
 
 - **A**: Pick the desired assembly to modify.
 - **1**: Choose a material from materials in the `Material Editor`.
@@ -46,7 +46,7 @@ By clicking an assembly, the `Layer editor` is specified and changes can be made
 ## Advanced controls
 In the advanced controls, it is possible to apply a specific Q-range of interest and sample constraints on the model.
 
-<img src='./../_images/sample_adv.png' width='800px'></img>
+![Advanced controls](./_images/sample_adv.png)
 
 - **A**: Setting min. Q value of interest.
 - **B**: Setting max. Q value of interest.

diff --git a/docs/tutorials/settings/settings.md → docs/src/tutorials/settings.md b/docs/tutorials/settings/settings.md → docs/src/tutorials/settings.md
@@ -1,20 +1,20 @@
 # Settings
 The settings can be reached from all tabs by pressing the cogs icon the the top right corner.
 
-<img src='./../_images/setting_overview.png' width='800px'></img>
+![Settings overview](./_images/setting_overview.png)
 
 In the settings menu, there are five tabs:
-#### Prompts
+## Prompts
 Used for enabling/disabling tooltips.
 
-#### Updates
+## Updates
 Allowing the app to check for updates when starting and force-checking for updates.
 
-#### Appearance
+## Appearance
 Change the theme of the app between: Light, Dark and system mode.
 
-#### Experimental
+## Experimental
 Setting the overall zoom level of icons and buttons, and changing the language of the app (to be implemented).
 
-#### Develop
+## Develop
 Is for setting how the app will log errors.
diff --git a/docs/tutorials/fitting/simple_fitting.md → docs/src/tutorials/simple_fitting.md b/docs/tutorials/fitting/simple_fitting.md → docs/src/tutorials/simple_fitting.md
@@ -6,21 +6,15 @@ The super-phase (where the neutrons are incident first) is a silicon (Si) wafer
 Then a polymer film is attached to the silicon dioxide by some chemical method and this polymer film is solvated in heavy water (D<sub>2</sub>O) which also makes up the sub-phase of the system. 
 This is shown pictorially below, as a slab model. 
 
-<center>
-    <img src='./../_images/polymer_film.png' width='300px'></img>
-</center>
-<center>
-    A slab model description of the polymer film system.
-</center>
-<br></br>
+![A slab model description of the polymer film system.](./_images/polymer_film.png){width=50}
 
 Now for explaining the `Analysis` tab let's look at how the EasyReflectometryApp can fit. The tab is like the previous tabs split into two windows, a graph- and a data-window.<br>
 The graph window has the same functionality as the previous tabs, so it will not be explained further. The data window has two categories: `Basic` and `Advanced` controls.
 
 ## Basic controls 
 The basic controls is for fitting the variables.
 
-<img src='./../_images/anal_bsc.png' width='800px'></img>
+![Basic analytics](./_images/anal_bsc.png)
 
 - **A**: Picking the desired variable to use the slider for fine-tuning it.
 - **B**: Able to change the specific variable.
@@ -32,7 +26,7 @@ The basic controls is for fitting the variables.
 ## Advanced controls
 The advanced control is then for changing the calculation engine and setting the minimisation method.
 
-<img src='./../_images/anal_adv.png' width='800px'></img>
+![Advanced analytics](./_images/anal_adv.png)
 
 - **A**: Changing the calculation engine between `refnx` and `refl1d`.<br></br>
 - **B**: Setting the minimisation method for minimising variables.

diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst
diff --git a/pyproject.toml b/pyproject.toml
@@ -42,6 +42,16 @@ ci = [
   'dephell_licenses'
 ]
 
+docs = [
+    "myst_parser==4.0.1",
+    "nbsphinx==0.9.7",
+    "sphinx_autodoc_typehints==3.0.1",
+    "sphinx_book_theme==1.1.4",
+    "sphinx-copybutton==0.5.2",
+    "toml==0.10.2",
+    "sphinx==8.1.3",
+]
+
 [release]
 app_name = 'EasyReflectometryApp'
 family_name = 'EasyReflectometryApp'
-Original file line number
+Diff line change
@@ Expand Up / @@ -46,7 +46,7 @@ settings.ini* @@
     .ci/
     .idea/
     .vscode/
-    ci/
     #Snap
     *.snap