Bug 32966 - [DOCS] Build error on GitLab - sphinxcontrib.spelling extension error
Summary: [DOCS] Build error on GitLab - sphinxcontrib.spelling extension error
Status: RESOLVED FIXED
Alias: None
Product: Koha
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Main
Hardware: All All
: P5 - low major (vote)
Assignee: David Nind
QA Contact: Testopia
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2023-02-14 21:55 UTC by David Nind
Modified: 2023-08-24 23:05 UTC (History)
0 users

See Also:
Change sponsored?: ---
Patch complexity: ---
Documentation contact:
Documentation submission:
Text to go in the release notes:
Version(s) released in:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description David Nind 2023-02-14 21:55:52 UTC
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
Comment 1 David Nind 2023-02-14 22:23:09 UTC
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
Comment 2 David Nind 2023-02-14 22:33:02 UTC
To get the documentation building again, I am going to try option 2.
Comment 3 David Nind 2023-02-14 23:44:46 UTC
(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
Comment 4 David Nind 2023-02-15 06:45:55 UTC
It looks like this has solved the issue.

Will look at back porting to older versions of the manual.
Comment 5 David Nind 2023-04-18 10:22:48 UTC
Have updated the build process for 22.11.x, so the 22.11 manual should now build.
Comment 6 David Nind 2023-08-24 23:05:37 UTC
Closing this - if older versions of the manual need rebuilding, I will backport.