Cannot build the documentation in Python 3

[dizcza]

Apologies for spamming issues and pull requests.

ObsPy version: master branch
Ubuntu 20.04 LTS
Python 3.9

I'm trying to build the documentation as described in Sphinx-documentation and install_python.py. Firstly, it's no longer possible to install the required fixed dependeies in Python 3.9 that I'm using. Secondly, when I installed them partially (to the extent that pip allowed me to do) I hit the following error while running make html:

Traceback (most recent call last):
  File "/home/dizcza/PycharmProjects/other/obspy/misc/docs/make_citations.py", line 154, in <module>
    line = formats[entry.type].format_data(entry).plaintext()
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 130, in format_data
    return self.f(self.children, data, *self.args, **self.kwargs)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 189, in words
    return join(sep) [children].format_data(data)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 130, in format_data
    return self.f(self.children, data, *self.args, **self.kwargs)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 176, in join
    parts = [part for part in _format_list(children, data) if part]
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 176, in <listcomp>
    parts = [part for part in _format_list(children, data) if part]
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 150, in <genexpr>
    return (_format_data(part, data) for part in list_)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 146, in _format_data
    return f(data)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 130, in format_data
    return self.f(self.children, data, *self.args, **self.kwargs)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 189, in words
    return join(sep) [children].format_data(data)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 130, in format_data
    return self.f(self.children, data, *self.args, **self.kwargs)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 176, in join
    parts = [part for part in _format_list(children, data) if part]
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 176, in <listcomp>
    parts = [part for part in _format_list(children, data) if part]
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 150, in <genexpr>
    return (_format_data(part, data) for part in list_)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 146, in _format_data
    return f(data)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 130, in format_data
    return self.f(self.children, data, *self.args, **self.kwargs)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 189, in words
    return join(sep) [children].format_data(data)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 130, in format_data
    return self.f(self.children, data, *self.args, **self.kwargs)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 176, in join
    parts = [part for part in _format_list(children, data) if part]
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 176, in <listcomp>
    parts = [part for part in _format_list(children, data) if part]
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 150, in <genexpr>
    return (_format_data(part, data) for part in list_)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 146, in _format_data
    return f(data)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 130, in format_data
    return self.f(self.children, data, *self.args, **self.kwargs)
  File "/media/dizcza/media/miniconda3/envs/obspy/lib/python3.9/site-packages/pybtex/style/template.py", line 259, in field
    entry = context['entry']
TypeError: 'Entry' object is not subscriptable
make: *** [Makefile:70: citations] Error 1

The error is triggered by pybtex. Thirdly, there is an alternative to pybtex called sphinxcontrib-bibtex which I have no affiliation with. And last but not least, sphinx has changed a lot since v1.1, and you will definitely benefit from incorporating their new features, not to mention the fact that you still use python 2 to build the docs.

[d-chambers]

Apologies for spamming issues and pull requests.

No problem, we appreciate your interest and contributions.

We have been aware of the doc issues for quite some time, but have not quite managed to implement a lasting fix. Last I remember, @heavelock had made some progress on creating a docker container for building the docs (#2792) but I am not sure where it currently stands.

[heavelock]

Hey there! Indeed, I was working on it but due to some major life changes I did not have enough time to finish working on that. I will try to do some progress on that tomorrow because I will have some time to work on hobby projects.

[dizcza]

I've looked at the Dockerfile. If you manage to build the docs in a docker container, you can do the same in a Python3 virtualenv. Users could do this in their Python3 envs.
What I mean by this is that providing a standalone docker image or a Dockerfile is not enough unless it's being continuously tested on each PR or, which is better, will replace the Python2 docs routine you currently use to build the official documentation. But if you decide to stick with the old Python2 routine to build the docs and do provide a working container for Python3 it will be at least... strange.

[heavelock]

The idea was to change the old way of building docs too plus contenerize it. In the end there is so many not working and outdated solutions in the current method of building that trying to salvage it is not worth it.

[ThomasLecocq]

@dizcza what about continuing the work of #2662 ?

[dizcza]

@ThomasLecocq it's hardly possible to go through the changes but the outlined changes LGTM.
You can refer the PR to this issue to be automatically closed once it's merged.

[d-chambers]

Should be fixed with #2662