Skip to content

Commit 6c5d2f4

Browse files
StephenNnejiStephenNneji
authored
Add initial doc structure, deploy script and publish action (#222)
1 parent 8db66bd commit 6c5d2f4

22 files changed

Lines changed: 264 additions & 17 deletions

‎.github/workflows/integration_tests.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ jobs:
1414
python-version: ["3.10", "3.12"]
1515
runs-on: ${{ matrix.os }}
1616
steps:
17-
- uses: actions/checkout@v4
17+
- uses: actions/checkout@v6
1818
- name: Set up Conda environment from environment.yaml
1919
uses: conda-incubator/setup-miniconda@v3
2020
with:

‎.github/workflows/publish_docs.yaml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
paths:
7+
- 'doc/**'
8+
release:
9+
types: [published]
10+
11+
jobs:
12+
build:
13+
env:
14+
DOC_URL: "https://rascalsoftware.github.io/RasCAL-2/"
15+
runs-on: ubuntu-latest
16+
17+
steps:
18+
- uses: actions/checkout@v6
19+
with:
20+
path: main
21+
- name: Checkout gh-pages
22+
uses: actions/checkout@v6
23+
with:
24+
ref: gh-pages
25+
path: web
26+
- name: Set up Python
27+
uses: actions/setup-python@v6
28+
- name: Install dependencies
29+
run: |
30+
python -m pip install --upgrade pip
31+
pip install -r main/requirements-dev.txt
32+
- name: Build and Deploy Docs
33+
run: |
34+
cd main/doc
35+
make html
36+
python deploy.py ${{github.ref}}
37+
cd ../../web
38+
git config user.name github-actions
39+
git config user.email github-actions@github.com
40+
git add -A
41+
git commit -m "Publish Documentation" || true
42+
git push

‎.github/workflows/unit_tests.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ jobs:
1414
ruff:
1515
runs-on: ubuntu-latest
1616
steps:
17-
- uses: actions/checkout@v4
17+
- uses: actions/checkout@v6
1818
- uses: astral-sh/ruff-action@v3
1919
- run: ruff format --check
2020

@@ -28,7 +28,7 @@ jobs:
2828
runs-on: ${{ matrix.os }}
2929

3030
steps:
31-
- uses: actions/checkout@v4
31+
- uses: actions/checkout@v6
3232
- name: Set up Conda environment from environment.yaml
3333
uses: conda-incubator/setup-miniconda@v3
3434
with:

‎CONTRIBUTING.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,3 +97,11 @@ plugins
9797
Matlab, run as shown below
9898

9999
> ./build_installer.sh --remote --nomatlab
100+
101+
### MacOS
102+
1. Build the executable and run the **packaging/macos/make.sh** bash script, the script will create an Apple installer
103+
package (*.pkg) with the given version (e.g. 1.0.0) and architecture (e.g. x64, arm64) appended to the package name.
104+
105+
cd packaging/
106+
python build_exe.py
107+
./macos/make.sh $VERSION $ARCHITECTURE

‎doc/deploy.py‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
import json
2+
import os
3+
import shutil
4+
import sys
5+
from urllib.parse import urljoin
6+
7+
sys.path.insert(0, os.path.abspath(".."))
8+
9+
from rascal2 import RASCAL2_VERSION
10+
11+
12+
DOCS_PATH = os.path.abspath(os.path.dirname(__file__))
13+
BUILD_PATH = os.path.join(DOCS_PATH, 'build', 'html')
14+
ROOT_PATH = os.path.join(DOCS_PATH, "..", "..")
15+
16+
url = os.environ.get('DOC_URL', '')
17+
version = str(RASCAL2_VERSION)
18+
if len(sys.argv) > 1 and sys.argv[1].strip().endswith(version):
19+
doc_version = version
20+
else:
21+
doc_version = "dev"
22+
WEB_PATH = os.path.join(ROOT_PATH, "web", doc_version)
23+
24+
if os.path.isdir(WEB_PATH):
25+
shutil.rmtree(WEB_PATH, ignore_errors=True)
26+
27+
shutil.copytree(BUILD_PATH, WEB_PATH, ignore=shutil.ignore_patterns('.buildinfo', 'objects.inv', '.doctrees',
28+
'_sphinx_design_static'))
29+
30+
releases = [entry.name for entry in os.scandir(os.path.join(ROOT_PATH, "web")) if
31+
entry.is_dir() and entry.name != '.git']
32+
releases.sort()
33+
switch_list = []
34+
for release in releases:
35+
switch_list.append({'name': release,
36+
'version': release,
37+
'url': urljoin(url, release)})
38+
39+
SWITCHER_FILE = os.path.join(os.path.join(ROOT_PATH, "web", 'switcher.json'))
40+
with open(SWITCHER_FILE, 'w') as switcher_file:
41+
json.dump(switch_list, switcher_file)
42+
43+
INDEX_FILE = os.path.join(os.path.join(ROOT_PATH, "web", 'index.html'))
44+
45+
is_latest = (len(releases) > 1 and releases[-2] == doc_version)
46+
base_url = urljoin(url, f'{doc_version}/')
47+
index_url = urljoin(base_url, 'index.html')
48+
if not os.path.exists(INDEX_FILE) or is_latest:
49+
data = [
50+
'<!DOCTYPE html>\n',
51+
'<html>\n',
52+
' <head>\n',
53+
f' <title>Redirecting to {base_url}</title>\n',
54+
' <meta charset="utf-8">\n',
55+
f' <meta http-equiv="refresh" content="0; URL={index_url}">\n',
56+
f' <link rel="canonical" href="{index_url}">\n',
57+
' </head>\n',
58+
'</html>',
59+
]
60+
61+
with open(INDEX_FILE, 'w') as index_file:
62+
index_file.writelines(data)

‎doc/source/_static/custom.css‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
body {
2+
font-family: 'Open Sans', sans-serif;
3+
font-size: medium;
4+
}
5+
6+
html[data-theme=light] {
7+
--pst-color-background: #f8f8ff;
8+
--pst-color-primary: #0969da;
9+
--pst-color-secondary: #0969da;
10+
}
11+
12+
html[data-theme=dark] {
13+
--pst-color-secondary: var(--pst-color-primary);
14+
}
15+
16+
.toctree-wrapper li[class^=toctree-l]>a {
17+
font-size: medium !important;
18+
}
19+
20+
.bd-header .navbar-nav>.current>.nav-link {
21+
border-bottom: None !important;
22+
}
23+
24+
.bd-sidebar-primary div#rtd-footer-container {
25+
margin-top: 0px !important;
26+
margin-bottom: 0px !important;
27+
}
28+
29+
.sd-tab-label{
30+
text-transform: lowercase;
31+
}
32+
33+
.sd-tab-label::first-letter {
34+
text-transform: uppercase;
35+
}
36+
37+
.tab-label-hidden .sd-tab-label{
38+
display: none;
39+
}
40+
41+
.tab-label-hidden .sd-tab-content{
42+
box-shadow: none;
43+
}
44+
45+
.tab-label-hidden pre{
46+
border: none;
47+
padding: 0;
48+
margin: 0;
49+
}
50+
51+
#rat{
52+
margin-bottom: 1.5em;
53+
}
54+
55+
.sd-card-header{
56+
font-weight: 550;
57+
}

‎doc/source/_static/logo.png‎

111 KB
Loading

‎doc/source/conf.py‎

Lines changed: 32 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,21 @@
55

66
# -- Project information -----------------------------------------------------
77
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
import os
9+
import sys
10+
import datetime
11+
12+
sys.path.insert(0, os.path.abspath("../.."))
13+
14+
from rascal2 import RASCAL2_VERSION
15+
816

917
project = 'RasCAL-2'
10-
copyright = '2025, ISIS Neutron and Muon Source'
18+
copyright = u"2024-{}, ISIS Neutron and Muon Source".format(datetime.date.today().year)
1119
author = 'ISIS Neutron and Muon Source'
12-
release = 'alpha'
13-
20+
version = RASCAL2_VERSION
21+
# The full version, including alpha/beta/rc tags.
22+
release = version
1423
# -- General configuration ---------------------------------------------------
1524
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
1625

@@ -19,10 +28,27 @@
1928
templates_path = ['_templates']
2029
exclude_patterns = []
2130

22-
23-
2431
# -- Options for HTML output -------------------------------------------------
2532
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
2633

27-
html_theme = 'alabaster'
34+
html_theme = "pydata_sphinx_theme"
35+
html_title = "RasCAL-2"
36+
html_logo = "_static/logo.png"
37+
html_favicon = "_static/logo.png"
2838
html_static_path = ['_static']
39+
html_css_files = ["custom.css"]
40+
html_copy_source = False
41+
html_show_sourcelink = False
42+
html_theme_options = {
43+
"show_prev_next": False,
44+
"logo": {
45+
"text": "RasCAL-2",
46+
},
47+
"icon_links": [
48+
{
49+
"name": "GitHub",
50+
"url": "https://github.com/RascalSoftware/RasCAL-2",
51+
"icon": "fa-brands fa-github",
52+
},
53+
],
54+
}

‎doc/source/dev.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Developer Guide
2+
===============
3+
4+
This is developer documentation for RasCAL-2. It contains information on how the
5+
project is structured.
6+
7+
.. toctree::
8+
:maxdepth: 2
9+
10+
dev/project
11+
dev/plot

doc/source/plot.rst renamed to doc/source/dev/plot.rst

File renamed without changes.

0 commit comments

Comments
 (0)