Dev/restructure2 (#6)

.github/workflows/checks.yaml

@@ -13,4 +13,6 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - uses: actions/setup-python@v5
+    - name: Install Dependencies
+      run: pip install -r requirements.txt
     - uses: pre-commit/[email protected]

.pre-commit-config.yaml

@@ -12,14 +12,14 @@ repos:
    - id: clang-format
 
 - repo: https://github.com/ambv/black
-  rev: 24.2.0
+  rev: 24.4.2
   hooks:
   - id: black
     args: ['--line-length=79']
 
 
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.5.0
+  rev: v4.6.0
   hooks:
   - id: trailing-whitespace
   - id: end-of-file-fixer
@@ -51,3 +51,12 @@ repos:
   rev: v0.6.13
   hooks:
   - id: cmake-format
+
+- repo: local
+  hooks:
+  - id: sphinx
+    name: sphinx
+    entry: make -C src spelling linkcheck html
+    language: system
+    pass_filenames: false
+    always_run: true

README.rst

@@ -10,3 +10,47 @@ oneAPI Specification Web Site
 
 This repository contains the source files for the oneAPI Specification web
 site.
+
+Adding a New Release
+====================
+
+To add a new release to the site, follow these steps:
+
+* Create a release in the `oneAPI Specification`_ repository. Attach a build of
+  the spec (html & PDF) to the release. Follow the naming convention and
+  contents for previous releases.
+* Update ``site.yaml`` to include the URL for the release. Do not forget to
+  update the ``latest`` key.
+* Update releases page in ``src/index.rst``
+* Submit a PR with the changes. As part of the checks, the site will be built
+  and deployed for preview. Submit the PR from a branch in this repo, not a
+  fork. Preview requires access to GitHub secrets that are not available in a
+  fork. Look in the log for the Publish job to find the URL of the preview. It
+  will look like this::
+
+   Website draft URL: https://662cecf4606617cb73f85378--oneapi-spec.netlify.app
+
+* If everything looks good, merge the PR. The site will be built and deployed
+  to the main site.
+
+Site Layout
+===========
+
+The site layout is determined by the ``site.yaml`` file. A nested set of
+directories is described by a nested set of dictionaries. When a key is not a
+dictionary, it is assumed to be a URL for a release.
+
+Web Site Hosting
+================
+
+We are using Netlify because GitHub pages cannot handle sites > 1 Gbyte. Robert
+has the Netlify account. If you want to do a manual deploy (development or
+production), follow the procedure in ``.github/workflows/publish.yaml``. You
+will need to provide a token::
+
+   export NETLIFY_AUTH_TOKEN=your_token
+
+Get a token from Robert if you need to deploy to production. Otherwise, create
+your own site under your own account in Netlify.
+
+.. _oneAPI Specification: https://github.com/uxlfoundation/oneAPI-spec

requirements.txt

@@ -4,3 +4,4 @@ PyYAML
 Sphinx
 sphinx-book-theme
 sphinx-notfound-page
+sphinxcontrib-spelling

site.yaml

@@ -3,4 +3,10 @@ site:
     oneapi:
       latest: https://github.com/uxlfoundation/oneAPI-spec/releases/download/oneAPI-v1.3-rev-1/oneapi-spec-v1.3-rev-1.zip
       v1.3-rev-1: https://github.com/uxlfoundation/oneAPI-spec/releases/download/oneAPI-v1.3-rev-1/oneapi-spec-v1.3-rev-1.zip
+      v1.3-provisional-rev-1: https://github.com/uxlfoundation/oneAPI-spec/releases/download/oneAPI-v1.3-provisional-rev-1/oneapi-spec-v1.3-provisional-rev-1.zip
+      v1.2-rev-1: https://github.com/uxlfoundation/oneAPI-spec/releases/download/oneAPI-v1.2-rev-1/oneapi-spec-v1.2-rev-1.zip
+      v1.2-provisional-rev-1: https://github.com/uxlfoundation/oneAPI-spec/releases/download/oneAPI-v1.2-provisional-rev-1/oneapi-spec-v1.2-provisional-rev-1.zip
+      v1.1-rev-1: https://github.com/uxlfoundation/oneAPI-spec/releases/download/oneapi-v1.1-rev-1/oneapi-spec-v1.1-rev-1.zip
+      v1.1-provisional-rev-1: https://github.com/uxlfoundation/oneAPI-spec/releases/download/oneAPI-v1.1-provisional-rev-1/oneapi-spec-v1.1-provisional-rev-1.zip
+      v1.0-rev-3: https://github.com/uxlfoundation/oneAPI-spec/releases/download/v1.0-rev-3/oneapi-spec-v1.0-rev-3.zip
       v1.0-rev-1: https://github.com/uxlfoundation/oneAPI-spec/releases/download/v1.0-rev-1/oneapi-spec-v1.0-rev-1.zip

src/404.rst

@@ -4,10 +4,10 @@ Page Not Found
 
 We cannot find the page. Please try:
 
-- Starting the navigation from `https://oneapi-spec.uxlfoundation.org`_
+- Starting the navigation from `https://oneapi-spec.netlify.app`_
 - Clearing your `browser cache`_
 - Filing a `GitHub issue`_
 
-.. _`https://oneapi-spec.uxlfoundation.org`: https://oneapi-spec.uxlfoundation.org
+.. _`https://oneapi-spec.netlify.app`: https://oneapi-spec.netlify.app
 .. _`browser cache`: https://clear-my-cache.com/
 .. _`GitHub issue`: https://github.com/uxlfoundation/oneapi-spec/issues

src/conf.py

@@ -30,7 +30,10 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["notfound.extension"]
+extensions = [
+    "notfound.extension",
+    "sphinxcontrib.spelling",
+]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -55,4 +58,14 @@
 
 html_sidebars = {"**": []}
 
+# notfound (404) page configuration
 notfound_urls_prefix = ""
+
+# spelling configuration
+spelling_show_suggestions = True
+spelling_lang = "en_US"
+spelling_word_list_filename = "spelling_wordlist.txt"
+
+# linkcheck configuration
+# ignore relative links
+linkcheck_ignore = [r"^(?!https).*$"]