diff --git a/.github/workflows/integration_tests.yaml b/.github/workflows/integration_tests.yaml index 31a8dafe..62a8fa4b 100644 --- a/.github/workflows/integration_tests.yaml +++ b/.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: diff --git a/.github/workflows/publish_docs.yaml b/.github/workflows/publish_docs.yaml new file mode 100644 index 00000000..b9e4e178 --- /dev/null +++ b/.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 diff --git a/.github/workflows/unit_tests.yaml b/.github/workflows/unit_tests.yaml index 0e7886d9..7ffbaf7d 100644 --- a/.github/workflows/unit_tests.yaml +++ b/.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: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5a02c2d9..c824f819 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/doc/deploy.py b/doc/deploy.py new file mode 100644 index 00000000..cc2e1ccb --- /dev/null +++ b/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 = [ + '\n', + '\n', + ' \n', + f' Redirecting to {base_url}\n', + ' \n', + f' \n', + f' \n', + ' \n', + '', + ] + + with open(INDEX_FILE, 'w') as index_file: + index_file.writelines(data) diff --git a/doc/source/_static/custom.css b/doc/source/_static/custom.css new file mode 100644 index 00000000..72c65896 --- /dev/null +++ b/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; +} \ No newline at end of file diff --git a/doc/source/_static/logo.png b/doc/source/_static/logo.png new file mode 100644 index 00000000..ab7a1a84 Binary files /dev/null and b/doc/source/_static/logo.png differ diff --git a/doc/source/conf.py b/doc/source/conf.py index f74baa06..915693dc 100644 --- a/doc/source/conf.py +++ b/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", + }, + ], +} diff --git a/doc/source/dev.rst b/doc/source/dev.rst new file mode 100644 index 00000000..5f5bbed8 --- /dev/null +++ b/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 diff --git a/doc/source/plot.rst b/doc/source/dev/plot.rst similarity index 100% rename from doc/source/plot.rst rename to doc/source/dev/plot.rst diff --git a/doc/source/project.rst b/doc/source/dev/project.rst similarity index 100% rename from doc/source/project.rst rename to doc/source/dev/project.rst diff --git a/doc/source/example.rst b/doc/source/example.rst new file mode 100644 index 00000000..bac945d5 --- /dev/null +++ b/doc/source/example.rst @@ -0,0 +1,2 @@ +Examples +======== diff --git a/doc/source/guide.rst b/doc/source/guide.rst new file mode 100644 index 00000000..d8db07a7 --- /dev/null +++ b/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 + diff --git a/doc/source/index.rst b/doc/source/index.rst index 5f4c097c..8ba2c783 100644 --- a/doc/source/index.rst +++ b/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 `_. -This is developer documentation for RasCAL-2. It contains information on how the -project is structured. .. toctree:: - :maxdepth: 2 - :caption: Contents: + :hidden: + + Home + +.. toctree:: + :hidden: + :titlesonly: + + install + guide + example + dev - project - plot diff --git a/doc/source/install.rst b/doc/source/install.rst new file mode 100644 index 00000000..7070a009 --- /dev/null +++ b/doc/source/install.rst @@ -0,0 +1,3 @@ +Installation +============ +This section provides more detailed information about installing RasCAL-2 \ No newline at end of file diff --git a/doc/source/user/control.rst b/doc/source/user/control.rst new file mode 100644 index 00000000..d6b9ccb1 --- /dev/null +++ b/doc/source/user/control.rst @@ -0,0 +1,2 @@ +Controls Window +=============== diff --git a/doc/source/user/interface.rst b/doc/source/user/interface.rst new file mode 100644 index 00000000..2b3e8b94 --- /dev/null +++ b/doc/source/user/interface.rst @@ -0,0 +1,2 @@ +User Interface +============== diff --git a/doc/source/user/overview.rst b/doc/source/user/overview.rst new file mode 100644 index 00000000..a63e1e79 --- /dev/null +++ b/doc/source/user/overview.rst @@ -0,0 +1,2 @@ +General Overview +================ diff --git a/doc/source/user/plot.rst b/doc/source/user/plot.rst new file mode 100644 index 00000000..8235c2b7 --- /dev/null +++ b/doc/source/user/plot.rst @@ -0,0 +1,2 @@ +Plot Window +=========== diff --git a/doc/source/user/project.rst b/doc/source/user/project.rst new file mode 100644 index 00000000..1119c3d6 --- /dev/null +++ b/doc/source/user/project.rst @@ -0,0 +1,2 @@ +Project Window +============== diff --git a/doc/source/user/terminal.rst b/doc/source/user/terminal.rst new file mode 100644 index 00000000..602c77c9 --- /dev/null +++ b/doc/source/user/terminal.rst @@ -0,0 +1,2 @@ +Terminal Window +=============== diff --git a/requirements-dev.txt b/requirements-dev.txt index 674ed904..8ffbdcac 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -2,3 +2,4 @@ pytest pytest-cov ruff Sphinx +pydata-sphinx-theme