search

linuxmint / doc-developer-guide

The Linux Mint Developer Guide
20 stars 18 forks source link

sphinx dependency not met, cannot be installed via method provided #4

Open AMDphreak opened 4 years ago

AMDphreak commented 4 years ago

From https://github.com/AMDphreak/doc-developer-guide

ryan@ryan-ADATA:~/code/online/doc-developer-guide/docs$ make html
Running Sphinx v1.6.7
loading pickled environment... not yet created

Theme error:
sphinx_rtd_theme is no longer a hard dependency since version 1.4.0. Please install it manually.(pip install sphinx_rtd_theme)
Makefile:20: recipe for target 'html' failed
make: *** [html] Error 1

It does not tell me which version of python this make is using, so I installed sphinx_rtd_theme on both python 2.7.x and 3.x via pip and pip3. This resolved nothing.

No work-around available (afaik)

AMDphreak commented 4 years ago

The tutorial says to install sphinx without specifying a version of python and a version of sphinx. Installing with latest library invalidates the rtd theme. I have tested and successfully generated an HTML using the up to date sphinx library that uses the new theme. I will submit a PR. Please review my solution. The new theme doesn't have the green code blocks (which I think was intentionally selected for Mint). At the very least, the new docs will generate properly for developers.

Odyseus commented 4 years ago

Hello, @AMDphreak.

A couple of observations.

  1. The README instructs to install the python-sphinx package (which is the Python 2 implementation of Sphinx). I think that it should instruct to install the python3-sphinx package.
  2. I think the README should also instruct to install the python3-sphinx-rtd-theme package. I think that this documentation was initially written around Linux Mint 18.x. At that time the python3-sphinx-rtd-theme package was a dependency of the python3-sphinx package.
  3. The README should not instruct to install any package with pip. The use of a Python module installed from the repositories that depends on a Python module installed from pip is a recipe for disaster.
  4. Sphinx completely dropped Python 2 since version 2.0.0 (a year and a half ago). Ubuntu and Debian have been working on completely removing Python 2 and Python 2 packages for their next releases for several months now. The point that I'm making is that the python-sphinx package (the Python 2 implementation) might or might not be available in Ubuntu 20.04 in which Linux Mint 20 will be based.