search

readthedocs / blog

Read the Docs blog
https://blog.readthedocs.com
17 stars 56 forks source link

Adopt `sphinxext-opengraph` #108

Closed astrojuanlu closed 3 years ago

astrojuanlu commented 3 years ago

@humitos pointed me out to https://github.com/wpilibsuite/sphinxext-opengraph/, which would be interesting to test across RTD as we noted. I think a good first place to add it would be our blog, since we usually share posts on social media, and having OpenGraph tags would make them look nicer with little effort, in principle.

However, we are using an ancient version of Sphinx in our blog, and the extension requires Sphinx 2.0 or greater. Therefore, we would need to upgrade it first. Therefore, this is blocked on #107.

TheTripleV commented 3 years ago

I built these docs with sphinxext-opengraph force installed with Sphinx 1.7.9 and it seemed to build fine. I think we just mentally defaulted to a minimum version of 2 and never checked.

astrojuanlu commented 3 years ago

Thanks @TheTripleV for trying it out. However, if I understand correctly, this is impossible to do now in one stroke with modern versions of pip:

$ cat requirements.txt
Sphinx==1.7.9

# Used to rewrite the Atom feed to use absolute links
lxml==4.2.1

ablog==0.9.5
# This dependencie from ablog needs to be pinned
werkzeug==0.16.1

sphinxext-opengraph==0.4.2
$ pip --version
pip 21.1.2 from /home/juanlu/Projects/RTD/blog-venv/lib/python3.7/site-packages/pip (python 3.7)
$ pip install -r requirements.txt
...
ERROR: Cannot install -r requirements.txt (line 10), -r requirements.txt (line 6) and Sphinx==1.7.9 because these package versions have conflicting dependencies.

The conflict is caused by:
    The user requested Sphinx==1.7.9
    ablog 0.9.5 depends on sphinx>=1.6
    sphinxext-opengraph 0.4.2 depends on sphinx>=2.0

To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip attempt to solve the dependency conflict

ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/user_guide/#fixing-conflicting-dependencies
astrojuanlu commented 3 years ago

xref: https://github.com/executablebooks/MyST-Parser/pull/393 and https://twitter.com/choldgraf/status/1413151433516453895

the only blocker is #107