search

OpenDataServices / sphinx-base

The base Sphinx setup (recommonmark + internationalisation) for Open Data Services docs projects. Builds at https://sphinx-base.readthedocs.io
Other
3 stars 4 forks source link

Problem with latest Sphinx and I18N #3

Closed odscjames closed 2 years ago

odscjames commented 6 years ago

Didn't know where else to document this so triying here ...

I've been working on a repo with sphinx==1.7.5, trying I18N. It broke.

With an error in docutils:

document.settings has no attribute 'tab_width'

This is the patch that needs to be applied to docutils to fix the error: https://github.com/docutils-mirror/docutils/pull/14/commits/c8ffd504b65e4b4f2f00677545f10f1d5a515199

However, docutils has not released a version with that patch.

I couldn't install a version of docutils with a git commit because the source is in SVN. I couldn't install a version of docutils with a SVN version because the code in the master SVN branch is Python 2. I then tried creating our own git repo, and applying the patch by hand, but I couldn't because I couldn't get a full copy of the source code of docutils in Python 3, only Python 2.

In the end I downgraded the sphinx version to sphinx==1.6.7. Then I cried.

Bjwebb commented 6 years ago

You should be able to install that commit from the docutils-mirror on github with pip install -e git+https://github.com/docutils-mirror/docutils.git@c8ffd504b65e4b4f2f00677545f10f1d5a515199#egg=docutils

odscjames commented 6 years ago

I guess early on I didn't try that because it felt wrong to be locking to a patch that was just a P.R. and hadn't been merged in - It wouldn't have any further work. Tho later on I got frustrated enought to try and create a Python 3 mirror of the latest code so 🤷‍♂️ But generally this all feels very brittle and flakey in a way which isn't great.

Bjwebb commented 6 years ago

Yeah, agree that it's not great. At the very least though, it could be a useful way to check that the patch actually fixes the problem.

odscjames commented 6 years ago

Think I just hacked the source files by hand on my VM to verify that :-)

jpmckinney commented 4 years ago

Adding link to my prior work to get this working: https://ocds-babel.readthedocs.io/en/latest/api/translate.html#install-requirements-for-markdown-translation

Recently found https://sphinx-book-theme.readthedocs.io/en/latest/ which uses https://markdown-it-py.readthedocs.io/en/latest/ instead of CommonMark.py and https://myst-parser.readthedocs.io/en/latest/ instead of recommonmark. ExecutableBooks seems like a way more responsible maintainer than ReadTheDocs. See https://github.com/open-contracting/standard_profile_template/issues/37

jpmckinney commented 3 years ago

recommonmark will be sunset in about a month: https://github.com/readthedocs/recommonmark/issues/221

Bjwebb commented 2 years ago

This repo no longer uses recommonmark.