For the last few days, the pipeline for building the manual has failed with the error message: WARNING: Invalid configuration value found: 'language = None'. Update your configuration to a valid language code. Falling back to 'en' (English). Extension error: Could not import extension sphinxcontrib.spelling (exception: No module named 'sphinxcontrib.spelling') make[1]: *** [Makefile:137: epub] Error 2 make[1]: Leaving directory '/builds/koha-community/koha-manual' make: *** [Makefile:69: all_epub] Error 2 Cleaning up project directory and file based variables ERROR: Job failed: exit code 1
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
To get the documentation building again, I am going to try option 2.
(In reply to David Nind from comment #2) > To get the documentation building again, I am going to try option 2. Required two additional dependencies, which I have now added as follow-ups: - enchant-2 - pip3 install pyenchant
It looks like this has solved the issue. Will look at back porting to older versions of the manual.
Have updated the build process for 22.11.x, so the 22.11 manual should now build.
Closing this - if older versions of the manual need rebuilding, I will backport.