[Koha-bugs] [Bug 32966] [DOCS] Build error on GitLab - sphinxcontrib.spelling extension error

[bugzilla-daemon at bugs.koha-community.org]

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=32966

--- Comment #1 from David Nind <david at davidnind.com> ---
>From my quick analysis, it means that the sphinxcontrib.spelling extension
package is not installing correctly.

Option 1 - Remove requirement temporarily
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The spelling check is not required on production, but it would create issues
for local building and spell checking if it isn't included in the Sphinx
configuration (source/conf.py).

Option 2 - Install Sphinx using pip, instead of the Debian packages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This would provide the most up-to-date version.

Option 3 - Use a Python environment for requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Locally, I install the requirements for Sphinx using a Python environment[1] -
this seems to be the recommended way to avoid confusion with Python versions
and dependencies.

However, I don't really know how to do this using Gitlab CI/CD!


[1] Installing Sphinx locally using a Python environment
========================================================

This is how I have recently installed things to make building the documentation
work (since I moved to a new laptop and updated OS).

This was based on this tutorial:
https://realpython.com/python-virtual-environments-a-primer/

Installing Python
~~~~~~~~~~~~~~~~~

On Ubuntu 22.04, Python 3.10.6 is installed. In the past, with older OS
versions, I've had a lot of issues getting multiple versions of Python to play
nicely and using update-alternatives to set the current version.

Other Python modules to install:
* apt-get install python3-pip
* apt-get install python3-stemmer
* apt-get install python3.10-venv

Create a virtual environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Create a folder somewhere where your virtual environments will live, for
example: ~/environments
2. Create a virtual environment using venv: python3.10 -m venv sphinx-koha-docs
3. Activate the environment: source
~/environments/sphinx-koha-docs/bin/activate
4. Install the components required for Sphinx and the Koha documentation:
   . python -m pip install -U sphinx
   . python -m pip install -U sphinx_rtd_theme
   . python -m pip install -U sphinxcontrib-spelling
5. Go to the folder you have your copy of the Koha documentation
6. Build the documentation: make html

Everyday commands
~~~~~~~~~~~~~~~~~

Activate the environment: source ~/environments/sphinx-koha-docs/bin/activate
Deactivate the environment: deactivate
List packages installed in the environment: pip list

-- 
You are receiving this mail because:
You are the assignee for the bug.
You are watching all bug changes.