Re: Updating sphinx?

On Mon, Sep 07, 2020 at 01:36:57PM -0400, Kurt Mosiejczuk wrote:
> On Mon, Sep 07, 2020 at 12:03:17PM +0200, Dima Pasechnik wrote:
>
> > > Others have weighed in. I did send out an update to a version that
> > > still had python 2.x support. The question was raised if we needed to
> > > do that though. It has been suspected that most/all just use the binary
>
> > sphinx is an extendable python library, to use sphinx in a configurable way one
> > needs to be able to import sphinx modules in your Python code.
> > So it's not just "binary".
>
> I didn't say it was just binary. I said there was suspicion that most ports
> just *use* the supplied programs and not the library.
>
> > > to generate documentation rather than using the libraries (which would
> > > still potentially require the python2 version). I got distracted onto
> > > other things and have been busy otherwise. If you want to investigate
> > > that, it would be great.
> >
> > as already suggested, the most reasonable would be to rename the current sphinx port
> > sphinx2, and make the current (the currect stable version is 3.2.1),
> > Python 3-only, sphinx the default sphinx port.
>
> The most reasonable would be a intermediate step where we update to the last
> version that supports python 2. We're quite a bit older than that even.

In our project sagemath.org we had quite a bit of struggle moving from a a very old
sphinx (1.3) to 1.8, only to have more struggle to move to sphinx 3.

That is, moving to 1.8 for a questionable benefit of few python2-only packages
(I cannot find a meaningful way to find out which packages we are talking about,
by the way)
and only then to the current version
is going to require more work after all.

>
> The *best* solution would be finding out if any of those python 2 ports
> actually use sphinx as an extensible library, or if they just use the default
> tools. Creating a whole separate python2 port would be a silly move if
> none of the python2 ports in question use sphinx as a library.

I have never seen a Python package that uses sphinx but has no customisations
in docs/conf.py (which would be a standard location for sphinx config).
E.g. including links to other Python projects in rst docs
would typically be processed by intersphinx, which is a sphinx extension (and a module
in sphinx library).
Another extremely popular extension is autodoc, which automatically extracts documentation
from docstrings in the source and writes it into rst files.

I also don't understand why it's a "silly move". The package is already there, after all,
just renaming it is very cheap, unlike creating a package from scratch.

Dima