Skip to content

Update documentation build instructions to include windows #2251

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
gfardell wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

Update documentation build instructions to include windows #2251

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
75d52b7
Update documentation build instructions to include windows
gfardell Dec 24, 2025
b6fb44e
Merge branch 'master' into doc_build_instructions
gfardell Dec 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 40 additions & 26 deletions docs/source/developer_guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,35 +115,49 @@ Building documentation locally

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
a HTTP server to view the documentation.

#. Clone ``cil`` repo
#. 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_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:
To build the docs locally, you will need a working ``cil`` installation built from source. The documentation build process has two parts:

1. **Sphinx** builds the API documentation from the source code (docstrings and ``.rst`` files)
2. **Jekyll** builds the website pages from the ``pages`` folder

Prerequisites
^^^^^^^^^^^^^

Before building the documentation:

#. Follow the `build from source instructions <https://github.com/TomographicImaging/CIL/tree/master#building-cil-from-source-code>`_ to create a conda environment and build ``cil``
#. Navigate to the ``docs`` folder
#. Install documentation dependencies: ``conda env update -f docs_environment.yml``
#. Install `Ruby 3.2 <https://www.ruby-lang.org/en/documentation/installation/>`_
#. Install Jekyll dependencies:

- **Linux/macOS:** ``make web-deps``
- **Windows:** ``gem install bundler && bundle install``
- **If bundle install fails on Windows:** Run ``gem install google-protobuf --platform=ruby`` then retry ``bundle install``

Building and viewing
^^^^^^^^^^^^^^^^^^^^

**Linux/macOS:**

::
git clone --recurse-submodule git@github.com:TomographicImaging/CIL
cd CIL
sh scripts/create_local_env_for_cil_development_tests.sh -n NUMPY_VERSION -p PYTHON_VERSION -e ENVIRONMENT_NAME
conda activate ENVIRONMENT_NAME
pip install .
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 web-deps # install dependencies (requires ruby 3.2)

make dirhtml web serve

**Windows:**

::

# Replace BRANCH_NAME with your branch name
python mkdemos.py
sphinx-build -b dirhtml source build\BRANCH_NAME
python mkversions.py
bundle exec jekyll build -s pages
xcopy _site build\ /E /I /Y
python -m http.server -d build

Open http://localhost:8000 for the homepage, or http://localhost:8000/BRANCH_NAME/ to go directly to the docs. Press Ctrl+C to stop the server.

Notebooks gallery
-----------------

Expand Down
Loading