local (ruby) dev instructions

Author: casperdcl

.github/workflows/README.md

@@ -44,12 +44,23 @@ The [docs](./build.yml#L124) job:
 
 - creates a `miniconda` environment from [requirements-test.yml](../../scripts/requirements-test.yml) and [docs_environment.yml](../../docs/docs_environment.yml)
 - `cmake` builds & installs CIL into the `miniconda` environment
-- builds the HTML documentation with `sphinx`
+  + builds the HTML documentation with `sphinx`
+- installs ruby dependencies from [`Gemfile`](../../docs/Gemfile)
+  + builds the HTML landing page with `jekyll`
 - uploads a `DocumentationHTML` artifact (which can be downloaded to view locally for debugging)
-- pushes the HTML documentation to the `gh-pages` branch
-  + only if pushing to `master` or tagging (skipped if pushing to a branch or a PR)
+  + pushes the HTML documentation to the `gh-pages` branch
+    * only if pushing to `master` or tagging (skipped if pushing to a branch or a PR)
 
 > [!TIP]
 > The `docs` job builds the documentation and uploads it as an artifact called `DocumentationHTML`.
 > It can be found by going to the "Actions" tab, and selecting the appropriate run of `.github/workflows/build.yml`, or by clicking on the tick on the action in the "All checks have passed/failed" section of a PR. When viewing the "Summary" for the run of the action, there is an "Artifact" section at the bottom of the page.
-> Clicking on `DocumentationHTML` allows you to download a zip folder containing the built HTML files. This allows you to preview the documentation site before it is published.
+> Click on `DocumentationHTML` to download a zip archive of the built HTML files.
+> It must be extracted into a `CIL` subfolder to properly render locally:
+>
+> ```sh
+> mkdir CIL
+> unzip -d CIL DocumentationHTML.zip
+> python -m http.server
+> ```
+>
+> Then open a browser and navigate to <http://localhost:8000/CIL/> to view the documentation.

docs/Gemfile.lock

@@ -127,4 +127,4 @@ DEPENDENCIES
   jekyll-remote-theme
 
 BUNDLED WITH
-   2.5.6
+   2.5.9

docs/Makefile

@@ -19,6 +19,7 @@ help:
 serve:
 	@python -m http.server -d "$(BUILDDIR)"
 web-deps:
+	@gem install bundler
 	@bundle install
 web:
 	@$(JEKYLLBUILD) -s "$(JEKYLLSRCDIR)" $(JEKYLLOPTS)

docs/source/developer_guide.rst

@@ -88,7 +88,9 @@ Rendered
 Building documentation locally
 ------------------------------
 
-The easiest way to test changes to documentation is to build the docs locally. To do this, you will need a working ``cil`` installation.
+The easiest way to test documentation changes is to open a pull request and `download the rendered documentation from the CI <https://github.com/TomographicImaging/CIL/blob/master/.github/workflows/README.md>`_.
+
+Alternatively, to build the docs locally, you will need a working ``cil`` installation.
 For development of the documentation embedded within the source code itself (e.g. docstrings), you should build ``cil`` from source.
 
 The following steps can be used to create an environment that is suitable for building ``cil`` and its documentation, and to start
@@ -98,8 +100,10 @@ a HTTP server to view the documentation.
 #. Update conda with ``conda update -n base -c defaults conda``
 #. Follow the instructions `here <https://github.com/TomographicImaging/CIL/tree/master#building-cil-from-source-code>`_ to create a conda environment and build ``cil`` from source
 #. Go to ``docs`` folder
-#. Install packages from ``docs/docs_environment.yml``
-#. Build the documentation with ``make dirhtml``
+#. Install packages from ``docs_environment.yml``
+#. [Install Ruby version 3.2](https://www.ruby-lang.org/en/documentation/installation/#installers)
+#. Install the web dependencies with ``make web-deps``
+#. Build the documentation with ``make dirhtml web``
 #. Start an HTTP server with ``make serve`` to access the docs via `localhost:8000 <http://localhost:8000>`_.
 
 Example:
@@ -114,7 +118,8 @@ Example:
   cd docs
   conda update -n base -c defaults conda
   conda env update -f docs_environment.yml # with the name field set to ENVIRONMENT_NAME
-  make dirhtml serve
+  make web-deps  # install dependencies (requires ruby 3.2)
+  make dirhtml web serve
 
 Notebooks gallery
 -----------------