From b2a1b3921beab27909829b11055255eaa43b40d1 Mon Sep 17 00:00:00 2001 From: mEngstroem Date: Wed, 2 Apr 2025 15:37:52 +0200 Subject: [PATCH 01/12] restructered files and created a TOC to incorperate tutorials --- docs/index.md | 2 +- .../getting-started.md => tutorial.md} | 12 ++++++++++++ docs/tutorials/index.rst | 17 ----------------- docs/tutorials/{data => }/load_data.md | 4 ++-- .../{models/model-def.md => model_def.md} | 10 +++++----- docs/tutorials/{settings => }/settings.md | 12 ++++++------ docs/tutorials/{fitting => }/simple_fitting.md | 6 +++--- 7 files changed, 29 insertions(+), 34 deletions(-) rename docs/{tutorials/getting-started.md => tutorial.md} (90%) delete mode 100644 docs/tutorials/index.rst rename docs/tutorials/{data => }/load_data.md (84%) rename docs/tutorials/{models/model-def.md => model_def.md} (88%) rename docs/tutorials/{settings => }/settings.md (78%) rename docs/tutorials/{fitting => }/simple_fitting.md (93%) diff --git a/docs/index.md b/docs/index.md index 3be29a38..7b1a708f 100644 --- a/docs/index.md +++ b/docs/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 b/docs/tutorial.md similarity index 90% rename from docs/tutorials/getting-started.md rename to docs/tutorial.md index 9b2af885..c3613e07 100644 --- a/docs/tutorials/getting-started.md +++ b/docs/tutorial.md @@ -35,3 +35,15 @@ When a project is started two further buttons is visualised, and settings is the - **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 + +``` \ No newline at end of file diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst deleted file mode 100644 index e8604064..00000000 --- a/docs/tutorials/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. include:: GettingStarted.md - -.. toctree:: - :hidden: - :caption: Contents: - - Setting up a model/models - Loading data/data - Fitting data/fitting - Settings/settings - - -.. Indices and tables -.. ================== -.. * :ref:`genindex` -.. * :ref:`modindex` -.. * :ref:`search` diff --git a/docs/tutorials/data/load_data.md b/docs/tutorials/load_data.md similarity index 84% rename from docs/tutorials/data/load_data.md rename to docs/tutorials/load_data.md index 53c908d1..13bdbd17 100644 --- a/docs/tutorials/data/load_data.md +++ b/docs/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`. - + - **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. - + - **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 b/docs/tutorials/model_def.md similarity index 88% rename from docs/tutorials/models/model-def.md rename to docs/tutorials/model_def.md index 8b700ff2..a11b448d 100644 --- a/docs/tutorials/models/model-def.md +++ b/docs/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. - + - **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-6Å-2) and given a name for the material. - + - **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. - + - **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. - + - **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. - + - **A**: Setting min. Q value of interest. - **B**: Setting max. Q value of interest. diff --git a/docs/tutorials/settings/settings.md b/docs/tutorials/settings.md similarity index 78% rename from docs/tutorials/settings/settings.md rename to docs/tutorials/settings.md index d55639a8..a2d2103e 100644 --- a/docs/tutorials/settings/settings.md +++ b/docs/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. - + 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 b/docs/tutorials/simple_fitting.md similarity index 93% rename from docs/tutorials/fitting/simple_fitting.md rename to docs/tutorials/simple_fitting.md index a1324b76..b1a00390 100644 --- a/docs/tutorials/fitting/simple_fitting.md +++ b/docs/tutorials/simple_fitting.md @@ -7,7 +7,7 @@ Then a polymer film is attached to the silicon dioxide by some chemical method a This is shown pictorially below, as a slab model.
- +
A slab model description of the polymer film system. @@ -20,7 +20,7 @@ The graph window has the same functionality as the previous tabs, so it will not ## Basic controls The basic controls is for fitting the variables. - + - **A**: Picking the desired variable to use the slider for fine-tuning it. - **B**: Able to change the specific variable. @@ -32,7 +32,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. - + - **A**: Changing the calculation engine between `refnx` and `refl1d`.

- **B**: Setting the minimisation method for minimising variables. From b307f27ec4a1951794968d41aef3e2173033527c Mon Sep 17 00:00:00 2001 From: mEngstroem Date: Wed, 2 Apr 2025 15:45:42 +0200 Subject: [PATCH 02/12] Removed unused .rst file --- docs/adrs.rst | 16 ---------------- 1 file changed, 16 deletions(-) delete mode 100644 docs/adrs.rst diff --git a/docs/adrs.rst b/docs/adrs.rst deleted file mode 100644 index 1f2264ad..00000000 --- a/docs/adrs.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. highlight:: shell - -==== -ADRs -==== - -Throughout the development, there have been a couple of architectural decisions that we `record`_ here. -This will likely grow in future and comments on these are welcome (via a `Github issue`_). - -.. toctree:: - :maxdepth: 1 - - adrs/adr0001 - -.. _record: https://adr.github.io -.. _Github issue: https://github.com/easyScience/EasyReflectometryApp/issues/new From 1d3588341bdc2a4e9c3083ecfafba2a02661bd8b Mon Sep 17 00:00:00 2001 From: mEngstroem Date: Wed, 2 Apr 2025 16:00:26 +0200 Subject: [PATCH 03/12] Changed images to pandoc formating instead of html --- docs/tutorials/load_data.md | 4 ++-- docs/tutorials/model_def.md | 10 +++++----- docs/tutorials/settings.md | 2 +- docs/tutorials/simple_fitting.md | 12 +++--------- 4 files changed, 11 insertions(+), 17 deletions(-) diff --git a/docs/tutorials/load_data.md b/docs/tutorials/load_data.md index 13bdbd17..dfef8b39 100644 --- a/docs/tutorials/load_data.md +++ b/docs/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`. - +![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. - +![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/model_def.md b/docs/tutorials/model_def.md index a11b448d..23c8effb 100644 --- a/docs/tutorials/model_def.md +++ b/docs/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. - +![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-6Å-2) and given a name for the material. - +![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. - +![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. - +![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. - +![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.md b/docs/tutorials/settings.md index a2d2103e..7e8b9477 100644 --- a/docs/tutorials/settings.md +++ b/docs/tutorials/settings.md @@ -1,7 +1,7 @@ # Settings The settings can be reached from all tabs by pressing the cogs icon the the top right corner. - +![Settings overview](./_images/setting_overview.png) In the settings menu, there are five tabs: ## Prompts diff --git a/docs/tutorials/simple_fitting.md b/docs/tutorials/simple_fitting.md index b1a00390..28de12c5 100644 --- a/docs/tutorials/simple_fitting.md +++ b/docs/tutorials/simple_fitting.md @@ -6,13 +6,7 @@ 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 (D2O) which also makes up the sub-phase of the system. This is shown pictorially below, as a slab model. -
- -
-
- A slab model description of the polymer film system. -
-

+![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.
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. @@ -20,7 +14,7 @@ The graph window has the same functionality as the previous tabs, so it will not ## Basic controls The basic controls is for fitting the variables. - +![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. - +![Advanced analytics](./_images/anal_adv.png) - **A**: Changing the calculation engine between `refnx` and `refl1d`.

- **B**: Setting the minimisation method for minimising variables. From f72db87a94d22df2cdaa142dbec4b7f40cd2ae75 Mon Sep 17 00:00:00 2001 From: mEngstroem Date: Thu, 3 Apr 2025 09:26:08 +0200 Subject: [PATCH 04/12] Setup docs build workflow --- .github/workflows/documentation-build.yml | 51 +++++++++++++++++++++++ pyproject.toml | 9 ++++ 2 files changed, 60 insertions(+) create mode 100644 .github/workflows/documentation-build.yml diff --git a/.github/workflows/documentation-build.yml b/.github/workflows/documentation-build.yml new file mode 100644 index 00000000..69a87a5a --- /dev/null +++ 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 \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index bd4a352d..7adf2597 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -42,6 +42,15 @@ 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", +] + [release] app_name = 'EasyReflectometryApp' family_name = 'EasyReflectometryApp' From e8c74c07c5eed1eec53a4b949a7dc481e2f27651 Mon Sep 17 00:00:00 2001 From: mEngstroem Date: Thu, 3 Apr 2025 09:39:15 +0200 Subject: [PATCH 05/12] Fixes docs env --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index 7adf2597..596e2e40 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -49,6 +49,7 @@ docs = [ "sphinx_book_theme==1.1.4", "sphinx-copybutton==0.5.2", "toml==0.10.2", + "sphinx<8.2", ] [release] From 3b64a9ba01b8d56a7739e544187ad89cee7b5fe0 Mon Sep 17 00:00:00 2001 From: mEngstroem Date: Thu, 3 Apr 2025 09:48:43 +0200 Subject: [PATCH 06/12] Fixes path for scr in workflow --- .github/workflows/documentation-build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/documentation-build.yml b/.github/workflows/documentation-build.yml index 69a87a5a..c8c3eaae 100644 --- a/.github/workflows/documentation-build.yml +++ b/.github/workflows/documentation-build.yml @@ -43,7 +43,7 @@ jobs: uses: sphinx-notes/pages@master with: install_requirements: true - documentation_path: docs/src + documentation_path: docs - name: Push changes uses: ad-m/github-push-action@master continue-on-error: true From 593698ce80df3fd28167426d9ab9897f581a7e0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mads=20Engstr=C3=B8m?= <89266942+mEngstroem@users.noreply.github.com> Date: Thu, 3 Apr 2025 09:53:46 +0200 Subject: [PATCH 07/12] Update documentation-build.yml Fixes branch in workflow --- .github/workflows/documentation-build.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/documentation-build.yml b/.github/workflows/documentation-build.yml index c8c3eaae..e2de0ac8 100644 --- a/.github/workflows/documentation-build.yml +++ b/.github/workflows/documentation-build.yml @@ -25,7 +25,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@master + uses: actions/checkout@documentation-fixes with: fetch-depth: 0 # otherwise, you will failed to push refs to dest repo - name: Upgrade pip @@ -40,12 +40,12 @@ jobs: sudo apt install pandoc pip install . '.[docs]' - name: Build and Commit - uses: sphinx-notes/pages@master + uses: sphinx-notes/pages@documentation-fixes with: install_requirements: true documentation_path: docs - name: Push changes - uses: ad-m/github-push-action@master + uses: ad-m/github-push-action@documentation-fixes continue-on-error: true with: - branch: gh-pages \ No newline at end of file + branch: gh-pages From c319c46c6afcc3ebd540c2569fc7402597c6dd89 Mon Sep 17 00:00:00 2001 From: mEngstroem Date: Thu, 3 Apr 2025 10:27:39 +0200 Subject: [PATCH 08/12] Created src folder for all documentation to work with builder and fixed make files --- .github/workflows/documentation-build.yml | 2 +- .gitignore | 2 +- docs/Makefile | 2 +- docs/make.bat | 2 +- docs/{ => src}/_static/favicon.ico | Bin docs/{ => src}/adrs.md | 0 docs/{ => src}/adrs/adr0001.md | 0 docs/{ => src}/adrs/adr0001.rst | 0 docs/{ => src}/adrs/adr0002.rst | 0 docs/{ => src}/adrs/adr0003.rst | 0 docs/{ => src}/build.md | 0 docs/{ => src}/ci.md | 0 docs/{ => src}/ci/build.md | 0 docs/{ => src}/conf.py | 4 ++-- docs/{ => src}/index.md | 0 docs/{ => src}/tutorial.md | 0 docs/{ => src}/tutorials/_images/anal_adv.png | Bin docs/{ => src}/tutorials/_images/anal_bsc.png | Bin docs/{ => src}/tutorials/_images/exp_data.png | Bin docs/{ => src}/tutorials/_images/exp_load.png | Bin docs/{ => src}/tutorials/_images/home.png | Bin docs/{ => src}/tutorials/_images/polymer_film.png | Bin docs/{ => src}/tutorials/_images/polymer_film.svg | 0 docs/{ => src}/tutorials/_images/project.png | Bin docs/{ => src}/tutorials/_images/sample_adv.png | Bin docs/{ => src}/tutorials/_images/sample_layer.png | Bin .../{ => src}/tutorials/_images/sample_material.png | Bin docs/{ => src}/tutorials/_images/sample_model.png | Bin .../{ => src}/tutorials/_images/sample_overview.png | Bin docs/{ => src}/tutorials/_images/save_setting.png | Bin .../tutorials/_images/setting_overview.png | Bin docs/{ => src}/tutorials/load_data.md | 0 docs/{ => src}/tutorials/model_def.md | 0 docs/{ => src}/tutorials/settings.md | 0 docs/{ => src}/tutorials/simple_fitting.md | 0 35 files changed, 6 insertions(+), 6 deletions(-) rename docs/{ => src}/_static/favicon.ico (100%) rename docs/{ => src}/adrs.md (100%) rename docs/{ => src}/adrs/adr0001.md (100%) rename docs/{ => src}/adrs/adr0001.rst (100%) rename docs/{ => src}/adrs/adr0002.rst (100%) rename docs/{ => src}/adrs/adr0003.rst (100%) rename docs/{ => src}/build.md (100%) rename docs/{ => src}/ci.md (100%) rename docs/{ => src}/ci/build.md (100%) rename docs/{ => src}/conf.py (99%) mode change 100755 => 100644 rename docs/{ => src}/index.md (100%) rename docs/{ => src}/tutorial.md (100%) rename docs/{ => src}/tutorials/_images/anal_adv.png (100%) rename docs/{ => src}/tutorials/_images/anal_bsc.png (100%) rename docs/{ => src}/tutorials/_images/exp_data.png (100%) rename docs/{ => src}/tutorials/_images/exp_load.png (100%) rename docs/{ => src}/tutorials/_images/home.png (100%) rename docs/{ => src}/tutorials/_images/polymer_film.png (100%) rename docs/{ => src}/tutorials/_images/polymer_film.svg (100%) rename docs/{ => src}/tutorials/_images/project.png (100%) rename docs/{ => src}/tutorials/_images/sample_adv.png (100%) rename docs/{ => src}/tutorials/_images/sample_layer.png (100%) rename docs/{ => src}/tutorials/_images/sample_material.png (100%) rename docs/{ => src}/tutorials/_images/sample_model.png (100%) rename docs/{ => src}/tutorials/_images/sample_overview.png (100%) rename docs/{ => src}/tutorials/_images/save_setting.png (100%) rename docs/{ => src}/tutorials/_images/setting_overview.png (100%) rename docs/{ => src}/tutorials/load_data.md (100%) rename docs/{ => src}/tutorials/model_def.md (100%) rename docs/{ => src}/tutorials/settings.md (100%) rename docs/{ => src}/tutorials/simple_fitting.md (100%) diff --git a/.github/workflows/documentation-build.yml b/.github/workflows/documentation-build.yml index e2de0ac8..494939ca 100644 --- a/.github/workflows/documentation-build.yml +++ b/.github/workflows/documentation-build.yml @@ -43,7 +43,7 @@ jobs: uses: sphinx-notes/pages@documentation-fixes with: install_requirements: true - documentation_path: docs + documentation_path: docs/src - name: Push changes uses: ad-m/github-push-action@documentation-fixes continue-on-error: true diff --git a/.gitignore b/.gitignore index 73ae4b5e..60af99fa 100644 --- a/.gitignore +++ b/.gitignore @@ -46,7 +46,7 @@ settings.ini* .ci/ .idea/ .vscode/ -ci/ + #Snap *.snap diff --git a/docs/Makefile b/docs/Makefile index 0766adbf..b7913396 100644 --- 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/make.bat b/docs/make.bat index 6e253da8..85009c8b 100644 --- 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 b/docs/src/_static/favicon.ico similarity index 100% rename from docs/_static/favicon.ico rename to docs/src/_static/favicon.ico diff --git a/docs/adrs.md b/docs/src/adrs.md similarity index 100% rename from docs/adrs.md rename to docs/src/adrs.md diff --git a/docs/adrs/adr0001.md b/docs/src/adrs/adr0001.md similarity index 100% rename from docs/adrs/adr0001.md rename to docs/src/adrs/adr0001.md diff --git a/docs/adrs/adr0001.rst b/docs/src/adrs/adr0001.rst similarity index 100% rename from docs/adrs/adr0001.rst rename to docs/src/adrs/adr0001.rst diff --git a/docs/adrs/adr0002.rst b/docs/src/adrs/adr0002.rst similarity index 100% rename from docs/adrs/adr0002.rst rename to docs/src/adrs/adr0002.rst diff --git a/docs/adrs/adr0003.rst b/docs/src/adrs/adr0003.rst similarity index 100% rename from docs/adrs/adr0003.rst rename to docs/src/adrs/adr0003.rst diff --git a/docs/build.md b/docs/src/build.md similarity index 100% rename from docs/build.md rename to docs/src/build.md diff --git a/docs/ci.md b/docs/src/ci.md similarity index 100% rename from docs/ci.md rename to docs/src/ci.md diff --git a/docs/ci/build.md b/docs/src/ci/build.md similarity index 100% rename from docs/ci/build.md rename to docs/src/ci/build.md diff --git a/docs/conf.py b/docs/src/conf.py old mode 100755 new mode 100644 similarity index 99% rename from docs/conf.py rename to docs/src/conf.py index 37f591ba..3c7f8b60 --- a/docs/conf.py +++ b/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 b/docs/src/index.md similarity index 100% rename from docs/index.md rename to docs/src/index.md diff --git a/docs/tutorial.md b/docs/src/tutorial.md similarity index 100% rename from docs/tutorial.md rename to docs/src/tutorial.md diff --git a/docs/tutorials/_images/anal_adv.png b/docs/src/tutorials/_images/anal_adv.png similarity index 100% rename from docs/tutorials/_images/anal_adv.png rename to docs/src/tutorials/_images/anal_adv.png diff --git a/docs/tutorials/_images/anal_bsc.png b/docs/src/tutorials/_images/anal_bsc.png similarity index 100% rename from docs/tutorials/_images/anal_bsc.png rename to docs/src/tutorials/_images/anal_bsc.png diff --git a/docs/tutorials/_images/exp_data.png b/docs/src/tutorials/_images/exp_data.png similarity index 100% rename from docs/tutorials/_images/exp_data.png rename to docs/src/tutorials/_images/exp_data.png diff --git a/docs/tutorials/_images/exp_load.png b/docs/src/tutorials/_images/exp_load.png similarity index 100% rename from docs/tutorials/_images/exp_load.png rename to docs/src/tutorials/_images/exp_load.png diff --git a/docs/tutorials/_images/home.png b/docs/src/tutorials/_images/home.png similarity index 100% rename from docs/tutorials/_images/home.png rename to docs/src/tutorials/_images/home.png diff --git a/docs/tutorials/_images/polymer_film.png b/docs/src/tutorials/_images/polymer_film.png similarity index 100% rename from docs/tutorials/_images/polymer_film.png rename to docs/src/tutorials/_images/polymer_film.png diff --git a/docs/tutorials/_images/polymer_film.svg b/docs/src/tutorials/_images/polymer_film.svg similarity index 100% rename from docs/tutorials/_images/polymer_film.svg rename to docs/src/tutorials/_images/polymer_film.svg diff --git a/docs/tutorials/_images/project.png b/docs/src/tutorials/_images/project.png similarity index 100% rename from docs/tutorials/_images/project.png rename to docs/src/tutorials/_images/project.png diff --git a/docs/tutorials/_images/sample_adv.png b/docs/src/tutorials/_images/sample_adv.png similarity index 100% rename from docs/tutorials/_images/sample_adv.png rename to docs/src/tutorials/_images/sample_adv.png diff --git a/docs/tutorials/_images/sample_layer.png b/docs/src/tutorials/_images/sample_layer.png similarity index 100% rename from docs/tutorials/_images/sample_layer.png rename to docs/src/tutorials/_images/sample_layer.png diff --git a/docs/tutorials/_images/sample_material.png b/docs/src/tutorials/_images/sample_material.png similarity index 100% rename from docs/tutorials/_images/sample_material.png rename to docs/src/tutorials/_images/sample_material.png diff --git a/docs/tutorials/_images/sample_model.png b/docs/src/tutorials/_images/sample_model.png similarity index 100% rename from docs/tutorials/_images/sample_model.png rename to docs/src/tutorials/_images/sample_model.png diff --git a/docs/tutorials/_images/sample_overview.png b/docs/src/tutorials/_images/sample_overview.png similarity index 100% rename from docs/tutorials/_images/sample_overview.png rename to docs/src/tutorials/_images/sample_overview.png diff --git a/docs/tutorials/_images/save_setting.png b/docs/src/tutorials/_images/save_setting.png similarity index 100% rename from docs/tutorials/_images/save_setting.png rename to docs/src/tutorials/_images/save_setting.png diff --git a/docs/tutorials/_images/setting_overview.png b/docs/src/tutorials/_images/setting_overview.png similarity index 100% rename from docs/tutorials/_images/setting_overview.png rename to docs/src/tutorials/_images/setting_overview.png diff --git a/docs/tutorials/load_data.md b/docs/src/tutorials/load_data.md similarity index 100% rename from docs/tutorials/load_data.md rename to docs/src/tutorials/load_data.md diff --git a/docs/tutorials/model_def.md b/docs/src/tutorials/model_def.md similarity index 100% rename from docs/tutorials/model_def.md rename to docs/src/tutorials/model_def.md diff --git a/docs/tutorials/settings.md b/docs/src/tutorials/settings.md similarity index 100% rename from docs/tutorials/settings.md rename to docs/src/tutorials/settings.md diff --git a/docs/tutorials/simple_fitting.md b/docs/src/tutorials/simple_fitting.md similarity index 100% rename from docs/tutorials/simple_fitting.md rename to docs/src/tutorials/simple_fitting.md From 73ac22d39ea19ba00521391bb8d01b74b1784028 Mon Sep 17 00:00:00 2001 From: mEngstroem Date: Thu, 3 Apr 2025 10:51:01 +0200 Subject: [PATCH 09/12] Fixes sphinx errors after changing structure with /src folder --- docs/src/build.md | 4 ++-- docs/src/ci/build.md | 4 ++-- docs/src/tutorial.md | 6 +++--- pyproject.toml | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/src/build.md b/docs/src/build.md index da34ee65..1dc340ac 100644 --- a/docs/src/build.md +++ b/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/src/ci/build.md b/docs/src/ci/build.md index c29f4aa7..a7a15536 100644 --- a/docs/src/ci/build.md +++ b/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/src/tutorial.md b/docs/src/tutorial.md index c3613e07..e0695e7c 100644 --- a/docs/src/tutorial.md +++ b/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. - + - **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. - + - **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,7 +30,7 @@ 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. - + - **A**: Save project. - **B**: Reset to start. diff --git a/pyproject.toml b/pyproject.toml index 596e2e40..d58ec5ea 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -49,7 +49,7 @@ docs = [ "sphinx_book_theme==1.1.4", "sphinx-copybutton==0.5.2", "toml==0.10.2", - "sphinx<8.2", + "sphinx==8.1.3", ] [release] From 429cd397c4c28a7c307085ff812c90df939aa8f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mads=20Engstr=C3=B8m?= <89266942+mEngstroem@users.noreply.github.com> Date: Thu, 3 Apr 2025 10:55:38 +0200 Subject: [PATCH 10/12] Update documentation-build.yml --- .github/workflows/documentation-build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/documentation-build.yml b/.github/workflows/documentation-build.yml index 494939ca..b4fd74ab 100644 --- a/.github/workflows/documentation-build.yml +++ b/.github/workflows/documentation-build.yml @@ -43,7 +43,7 @@ jobs: uses: sphinx-notes/pages@documentation-fixes with: install_requirements: true - documentation_path: docs/src + documentation_path: docs/src/ - name: Push changes uses: ad-m/github-push-action@documentation-fixes continue-on-error: true From 0bd6c0374051ceeeb62f216d6d7bc018757db71a Mon Sep 17 00:00:00 2001 From: mEngstroem Date: Thu, 3 Apr 2025 11:03:59 +0200 Subject: [PATCH 11/12] change back to proper branches for actions, misunderstoood references --- .github/workflows/documentation-build.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/documentation-build.yml b/.github/workflows/documentation-build.yml index 494939ca..34d0e5d7 100644 --- a/.github/workflows/documentation-build.yml +++ b/.github/workflows/documentation-build.yml @@ -25,7 +25,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@documentation-fixes + uses: actions/checkout@master with: fetch-depth: 0 # otherwise, you will failed to push refs to dest repo - name: Upgrade pip @@ -40,12 +40,12 @@ jobs: sudo apt install pandoc pip install . '.[docs]' - name: Build and Commit - uses: sphinx-notes/pages@documentation-fixes + uses: sphinx-notes/pages@master with: install_requirements: true documentation_path: docs/src - name: Push changes - uses: ad-m/github-push-action@documentation-fixes + uses: ad-m/github-push-action@master continue-on-error: true with: branch: gh-pages From c1fc547b7c50809cc4debb805810d7ed4df4abc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mads=20Engstr=C3=B8m?= <89266942+mEngstroem@users.noreply.github.com> Date: Thu, 3 Apr 2025 11:15:36 +0200 Subject: [PATCH 12/12] Update documentation-build.yml --- .github/workflows/documentation-build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/documentation-build.yml b/.github/workflows/documentation-build.yml index 74325096..34d0e5d7 100644 --- a/.github/workflows/documentation-build.yml +++ b/.github/workflows/documentation-build.yml @@ -43,7 +43,7 @@ jobs: uses: sphinx-notes/pages@master with: install_requirements: true - documentation_path: docs/src/ + documentation_path: docs/src - name: Push changes uses: ad-m/github-push-action@master continue-on-error: true