Gradle build not working anymore after adding copybutton

[clausnagel]

I locally installed the Sphinx copybutton extension using pip install sphinx-copybutton.

However, when running the Gradle build task, it fails with the following error messages:

15:39:50.999 [QUIET] [system.out] Running Sphinx v3.4.3
15:39:51.146 [QUIET] [system.out] Original exception:
15:39:51.147 [QUIET] [system.out] Traceback (most recent call last):
15:39:51.147 [QUIET] [system.out]   File "sphinx\registry.py", line 417, in load_extension
15:39:51.147 [QUIET] [system.out]   File "importlib\__init__.py", line 127, in import_module
15:39:51.147 [QUIET] [system.out]   File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
15:39:51.147 [QUIET] [system.out]   File "<frozen importlib._bootstrap>", line 983, in _find_and_load
15:39:51.147 [QUIET] [system.out]
15:39:51.147 [QUIET] [system.out]   File "<frozen importlib._bootstrap>", line 965, in _find_and_load_unlocked
15:39:51.147 [QUIET] [system.out] ModuleNotFoundError: No module named 'sphinx_copybutton'
15:39:51.147 [QUIET] [system.out]
15:39:51.147 [QUIET] [system.out] Traceback (most recent call last):
15:39:51.148 [QUIET] [system.out]   File "sphinx\registry.py", line 417, in load_extension
15:39:51.148 [QUIET] [system.out]   File "importlib\__init__.py", line 127, in import_module
15:39:51.148 [QUIET] [system.out]   File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
15:39:51.148 [QUIET] [system.out]   File "<frozen importlib._bootstrap>", line 983, in _find_and_load
15:39:51.148 [QUIET] [system.out]   File "<frozen importlib._bootstrap>", line 965, in _find_and_load_unlocked
15:39:51.148 [QUIET] [system.out] ModuleNotFoundError: No module named 'sphinx_copybutton'
15:39:51.148 [QUIET] [system.out]
15:39:51.148 [QUIET] [system.out] The above exception was the direct cause of the following exception:
15:39:51.148 [QUIET] [system.out]
15:39:51.148 [QUIET] [system.out] Traceback (most recent call last):
15:39:51.148 [QUIET] [system.out]   File "sphinx\cmd\build.py", line 279, in build_main
15:39:51.148 [QUIET] [system.out]   File "sphinx\application.py", line 245, in __init__
15:39:51.148 [QUIET] [system.out]   File "sphinx\application.py", line 402, in setup_extension
15:39:51.148 [QUIET] [system.out]   File "sphinx\registry.py", line 421, in load_extension
15:39:51.148 [QUIET] [system.out] sphinx.errors.ExtensionError: Could not import extension sphinx_copybutton (exception: No module named 'sphinx_copybutton')

[BWibo]

I never used gradle to build this before. I build locally using the make files and my local Python env:

# Setup env -------------------------------------
pip install -U sphinx
pip install -U -r source/requirements.txt

# or
pip install -U sphinx
pip install -U sphinx-rtd-theme
pip install -U sphinx_copybutton

# Build docs  -----------------------------------
make html

Or I use this Docker image I maintain: https://github.com/BWibo/sphinx-rtd-docker

docker run --rm \
    -v $PWD:/docs \
  bwibo/sphinx-rtd make html

I did some reading and found that the Gradle plugin we are using does not support adding custom extension at the moment.

• https://trustin.github.io/sphinx-gradle-plugin/
• Support of other Sphinx extensions trustin/sphinx-gradle-plugin#10

However, according to the issue the workaround you tried for getting the copybutton to work on the RTD platform seems to work here. I just tried that. The build is running with some warnings but seems to complete:

Running Sphinx v3.4.3
Adding copy buttons to code blocks...
loading pickled environment... done
WARNING: file 'base_library.zip' on theme path is not a valid zipfile or contains no theme
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 217 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed

...
...
...

copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 10 warnings.

The HTML pages are in ../build.

> Task :sphinx
Sphinx exited with code 0. Took 49016ms.

BUILD SUCCESSFUL in 1m 7s
1 actionable task: 1 executed

The built HTML seems fine, but there is no copy button. So this fix is just partially working.
Anyway, I'm not a big fan of that solution as it would add some 3rd party code to the repo we would have to maintain and test.

Do we need a Gradle build for this or is building locally as described above acceptable as well?
the Gradle plugin has some disadvantages:

• Outdate Sphinx version: 3.4.3, latest via pip is 4.2.0
• Cannot be extended easily. The local env and the Docker image can easily be extend, if required.
  For instance, use this extension for my personal docs to make them more vivid.
  https://sphinxemojicodes.readthedocs.io/en/stable/

[clausnagel]

Thanks for your in-depth evaluation, @BWibo.

@yaozhihang, what do you think, can we get rid of the Gradle integration?

[yaozhihang]

The Gradle Plugin is currently not used in any pipelines. So yes, we can get rid of it. The Docker image of @BWibo is very nice alternative allowing us build the docs quickly in local.

[clausnagel]

Ok, great, no objection from my side.

[BWibo]

OK, I'll add a PR to drop the Gradle stuff then. One question: Is README.rst used for anything else but Github landing page?
If not, I would add a section at the bottom decribing how to build the docs locally and add a reference to the Docs on readthedocs.io.

[clausnagel]

Good question, I think we mainly used the README.rst as cover page for PDF exports. But since we dropped PDF exports, we can use (and restructure) it as Github landing page. Maybe also rename to README.md then?

[yaozhihang]

Maybe we could add a README.md and keep the README.rst as it is, since we may want to have PDF exports in future?

[BWibo]

👍 I'll add this to the PR. I'm wondering if github is going to pickup RST or MD as landing page then.
Edit: The MD file is used.