Basic docs

.github/workflows/integration_tests.yaml

@@ -14,7 +14,7 @@ jobs:
         python-version: ["3.10", "3.12"]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4      
+      - uses: actions/checkout@v6      
       - name: Set up Conda environment from environment.yaml
         uses: conda-incubator/setup-miniconda@v3
         with:

.github/workflows/publish_docs.yaml

@@ -0,0 +1,42 @@
+name: Docs
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+    - 'doc/**'
+  release:
+    types: [published]
+
+jobs:
+  build:
+    env:
+      DOC_URL: "https://rascalsoftware.github.io/RasCAL-2/"
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        path: main
+    - name: Checkout gh-pages
+      uses: actions/checkout@v6
+      with:
+        ref: gh-pages
+        path: web
+    - name: Set up Python
+      uses: actions/setup-python@v6
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r main/requirements-dev.txt
+    - name: Build and Deploy Docs
+      run: |
+        cd main/doc
+        make html
+        python deploy.py ${{github.ref}}
+        cd ../../web
+        git config user.name github-actions
+        git config user.email github-actions@github.com
+        git add -A
+        git commit -m "Publish Documentation" || true
+        git push

.github/workflows/unit_tests.yaml

@@ -14,7 +14,7 @@ jobs:
   ruff:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: astral-sh/ruff-action@v3
       - run: ruff format --check
 
@@ -28,7 +28,7 @@ jobs:
     runs-on: ${{ matrix.os }}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up Conda environment from environment.yaml
         uses: conda-incubator/setup-miniconda@v3
         with:

CONTRIBUTING.md

@@ -97,3 +97,11 @@ plugins
    Matlab, run as shown below
 
        > ./build_installer.sh --remote --nomatlab
+
+### MacOS
+1. Build the executable and run the **packaging/macos/make.sh** bash script, the script will create an Apple installer 
+   package (*.pkg) with the given version (e.g. 1.0.0) and architecture (e.g. x64, arm64) appended to the package name.  
+
+        cd packaging/
+        python build_exe.py
+        ./macos/make.sh $VERSION $ARCHITECTURE

doc/deploy.py

@@ -0,0 +1,62 @@
+import json
+import os
+import shutil
+import sys
+from urllib.parse import urljoin
+
+sys.path.insert(0, os.path.abspath(".."))
+
+from rascal2 import RASCAL2_VERSION
+
+
+DOCS_PATH = os.path.abspath(os.path.dirname(__file__))
+BUILD_PATH = os.path.join(DOCS_PATH, 'build', 'html')
+ROOT_PATH = os.path.join(DOCS_PATH, "..", "..")
+
+url = os.environ.get('DOC_URL', '')
+version = str(RASCAL2_VERSION)
+if len(sys.argv) > 1 and sys.argv[1].strip().endswith(version):
+    doc_version = version
+else:
+    doc_version = "dev"
+WEB_PATH = os.path.join(ROOT_PATH, "web", doc_version)
+
+if os.path.isdir(WEB_PATH):
+    shutil.rmtree(WEB_PATH, ignore_errors=True)
+
+shutil.copytree(BUILD_PATH, WEB_PATH, ignore=shutil.ignore_patterns('.buildinfo', 'objects.inv', '.doctrees',
+                                                                    '_sphinx_design_static'))
+
+releases = [entry.name for entry in os.scandir(os.path.join(ROOT_PATH, "web")) if
+            entry.is_dir() and entry.name != '.git']
+releases.sort()
+switch_list = []
+for release in releases:
+    switch_list.append({'name': release,
+                        'version': release,
+                        'url': urljoin(url, release)})
+
+SWITCHER_FILE = os.path.join(os.path.join(ROOT_PATH, "web", 'switcher.json'))
+with open(SWITCHER_FILE, 'w') as switcher_file:
+    json.dump(switch_list, switcher_file)
+
+INDEX_FILE = os.path.join(os.path.join(ROOT_PATH, "web", 'index.html'))
+
+is_latest = (len(releases) > 1 and releases[-2] == doc_version)
+base_url = urljoin(url, f'{doc_version}/')
+index_url = urljoin(base_url, 'index.html')
+if not os.path.exists(INDEX_FILE) or is_latest:
+    data = [
+        '<!DOCTYPE html>\n',
+        '<html>\n',
+        '  <head>\n',
+        f'    <title>Redirecting to {base_url}</title>\n',
+        '    <meta charset="utf-8">\n',
+        f'    <meta http-equiv="refresh" content="0; URL={index_url}">\n',
+        f'    <link rel="canonical" href="{index_url}">\n',
+        '  </head>\n',
+        '</html>',
+    ]
+
+    with open(INDEX_FILE, 'w') as index_file:
+        index_file.writelines(data)

doc/source/_static/custom.css

@@ -0,0 +1,57 @@
+body {
+  font-family: 'Open Sans', sans-serif;
+  font-size: medium;
+}
+
+html[data-theme=light] {
+  --pst-color-background: #f8f8ff;
+  --pst-color-primary: #0969da;
+  --pst-color-secondary: #0969da;
+}
+
+html[data-theme=dark] {
+  --pst-color-secondary: var(--pst-color-primary);
+}
+
+.toctree-wrapper li[class^=toctree-l]>a {
+  font-size: medium !important;
+}
+
+.bd-header .navbar-nav>.current>.nav-link {
+  border-bottom: None !important;
+}
+
+.bd-sidebar-primary div#rtd-footer-container {
+  margin-top: 0px !important;
+  margin-bottom: 0px !important;
+}
+
+.sd-tab-label{
+  text-transform: lowercase;
+}
+
+.sd-tab-label::first-letter {
+  text-transform: uppercase;
+}
+
+.tab-label-hidden .sd-tab-label{
+  display: none;
+}
+
+.tab-label-hidden .sd-tab-content{
+  box-shadow: none;
+}
+
+.tab-label-hidden pre{
+  border: none;
+  padding: 0;
+  margin: 0;
+}
+
+#rat{
+  margin-bottom: 1.5em;
+}
+
+.sd-card-header{
+  font-weight: 550;
+}

doc/source/conf.py

@@ -5,12 +5,21 @@
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import os
+import sys
+import datetime
+
+sys.path.insert(0, os.path.abspath("../.."))
+
+from rascal2 import RASCAL2_VERSION
+
 
 project = 'RasCAL-2'
-copyright = '2025, ISIS Neutron and Muon Source'
+copyright = u"2024-{}, ISIS Neutron and Muon Source".format(datetime.date.today().year)
 author = 'ISIS Neutron and Muon Source'
-release = 'alpha'
-
+version = RASCAL2_VERSION
+# The full version, including alpha/beta/rc tags.
+release = version
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
@@ -19,10 +28,27 @@
 templates_path = ['_templates']
 exclude_patterns = []
 
-
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'alabaster'
+html_theme = "pydata_sphinx_theme"
+html_title = "RasCAL-2"
+html_logo = "_static/logo.png"
+html_favicon = "_static/logo.png"
 html_static_path = ['_static']
+html_css_files = ["custom.css"]
+html_copy_source = False
+html_show_sourcelink = False
+html_theme_options = {
+    "show_prev_next": False,
+    "logo": {
+        "text": "RasCAL-2",
+    },
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/RascalSoftware/RasCAL-2",
+            "icon": "fa-brands fa-github",
+        },
+    ],
+}

doc/source/dev.rst

@@ -0,0 +1,11 @@
+Developer Guide
+===============
+
+This is developer documentation for RasCAL-2. It contains information on how the
+project is structured.
+
+.. toctree::
+   :maxdepth: 2
+
+   dev/project
+   dev/plot

doc/source/example.rst

@@ -0,0 +1,2 @@
+Examples
+========

doc/source/guide.rst

@@ -0,0 +1,14 @@
+User Guide
+==========
+
+
+.. toctree::
+   :maxdepth: 2
+
+   user/overview
+   user/interface
+   user/control
+   user/plot
+   user/project
+   user/terminal
+

doc/source/index.rst

@@ -1,12 +1,21 @@
-RasCAL-2 developer documentation
-================================
+RasCAL-2
+========
+
+RasCAL-2 is a software for the analysis of multi-contrast neutron reflectometry data.
+It is a graphical user interface (GUI) for the `Python RAT API <https://github.com/RascalSoftware/python-RAT>`_.
 
-This is developer documentation for RasCAL-2. It contains information on how the 
-project is structured.
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+   :hidden:
+
+   Home <self>
+
+.. toctree::
+   :hidden:
+   :titlesonly:
+
+   install
+   guide
+   example
+   dev
 
-   project
-   plot

doc/source/install.rst

@@ -0,0 +1,3 @@
+Installation
+============
+This section provides more detailed information about installing RasCAL-2

doc/source/user/control.rst

@@ -0,0 +1,2 @@
+Controls Window
+===============

doc/source/user/interface.rst

@@ -0,0 +1,2 @@
+User Interface
+==============

doc/source/user/overview.rst

@@ -0,0 +1,2 @@
+General Overview
+================

doc/source/user/plot.rst

@@ -0,0 +1,2 @@
+Plot Window
+===========

doc/source/user/project.rst

@@ -0,0 +1,2 @@
+Project Window
+==============

doc/source/user/terminal.rst

@@ -0,0 +1,2 @@
+Terminal Window
+===============

requirements-dev.txt

@@ -2,3 +2,4 @@ pytest
 pytest-cov
 ruff
 Sphinx
+pydata-sphinx-theme