documentation of external packages

[Vincent Delecroix]

Dear all,

I think we reached a consensus that we should have more and more
of the sage source code made as independent Python packages. This
effort has already started with cysignals, cypari2, pplpy and
gappy.

However, this externalizations comes with some inconvenience and
I would like to discuss one issue with documentation that was
raised in ticket #31404. Namely, the problem is that we want
something like `:mod:cypari2.gen` inside sage documentation to be
resolved by sphinx to what it should be (that could be: a link
to the documentation in SAGE_SHARE, to the local system
documentation on the computer or to online documentation). If
all these standard sage packages would install their documentation
in `$SAGE_SHARE` that would be easy, but I don't think we want to
assume such a thing in general (eg linux distributions do not).
One problem is that the cypari2 Python library does not know if
and where its documentation has been installed.

On linux platforms they solve this issue by making two distinct
packages: one for the library one for the documentation. Should
we also have this duplication library versus documentation for
each package?

See also the related ticket #27495

Cheers
Vincent

[William Stein]

On Tue, Feb 16, 2021 at 10:45 AM Vincent Delecroix <20100.d...@gmail.com> wrote:

I think we reached a consensus that we should have more and more
of the sage source code made as independent Python packages.

I just want to say "As the person who started Sage, huge +1 to having more and more of Sage made as independent Python packages!"

--

William (http://wstein.org)

[Matthias Koeppe]

On Tuesday, February 16, 2021 at 10:45:30 AM UTC-8 vdelecroix wrote:

However, this externalizations comes with some inconvenience and
I would like to discuss one issue with documentation that was
raised in ticket #31404. Namely, the problem is that we want
something like `:mod:cypari2.gen` inside sage documentation to be
resolved by sphinx to what it should be (that could be: a link
to the documentation in SAGE_SHARE, to the local system
documentation on the computer or to online documentation).

My suggestion would be to focus on linking to online versions of package documentation first.

Ticket https://trac.sagemath.org/ticket/27495 already describes a proposed design for this - comments and help with the implementation are welcome.

Providing links to an offline copy of package documentation is secondary, in my opinion. But nevertheless, here are some thoughts:

Splitting out the documentation of pplpy (as an example) into a separate package pplpy-doc could be a good design for various reasons:

1) pplpy-doc could be distributed as an architecture-independent wheel. 

2) Building pplpy would not need Sphinx as a build system requirement (note that in modern Python packaging following PEP517/518, there is no such thing as an "optional build system requirement").

3) Clear separation between the front-end environment and the kernel environment, as explained in https://trac.sagemath.org/ticket/30306 - pplpy-doc would be installed in the front-end environment (where the Jupyter notebook runs) and will not be needed in the kernel environment; whereas pplpy would not be needed in the front-end environment.

4) Using "extra-requires", installing pplpy with offline documentation could just be "pip install pplpy[doc]" (which would add the dependency on pplpy-doc)

For a proposal for packaging of the documentation of Sage itself - please see https://trac.sagemath.org/ticket/29868 (pip-installable packages sagemath-doc-src, sagemath-doc-inventory, sagemath-doc-html, sagemath-doc-pdf) - comments and help with the implementation are welcome here too.

Matthias

[Michael Orlitzky]

On Tue, 2021-02-16 at 19:43 +0100, Vincent Delecroix wrote:
> Dear all,
>
> I think we reached a consensus that we should have more and more
> of the sage source code made as independent Python packages. This
> effort has already started with cysignals, cypari2, pplpy and
> gappy.
>
> However, this externalizations comes with some inconvenience and
> I would like to discuss one issue with documentation that was
> raised in ticket #31404. Namely, the problem is that we want
> something like `:mod:cypari2.gen` inside sage documentation to be
> resolved by sphinx to what it should be (that could be: a link
> to the documentation in SAGE_SHARE, to the local system
> documentation on the computer or to online documentation).

Sphinx creates inventory files that can be used for cross-referencing:

https://www.sphinx-doc.org/en/1.5/ext/intersphinx.html#module-sphinx.ext.intersphinx

The trick is then to inform the sage build system of all the various
locations where those inventory files might be hidden. It wouldn't be
pretty, but we could probably just "try them all" in spkg-configure.m4
if there are no smarter ideas. This would only need to be done for the
packages that are referenced externally.

Failure to locate the docs should be nonfatal in my opinion. If I have
gone out of my way to install a system package without the
documentation, I'd rather sage not second-guess me and waste time/space
building it anyway for the sake of a cross-reference.

[E. Madison Bray]

I think by default we should just be using the online intersphinx
links (I am surprised to learn we didn't do this already).
Intersphinx mappings can also be made to local copies of docs for
different projects, most of which Sage does not even build or install
(e.g. the Python docs, which we should have intersphinx mappings to).

By default the conf.py could use the URLs for online versions of the
docs, but provide an environment variable or something to provide
alternate paths to each of the third-party docs, so that it can easily
be customized by packagers to link to local docs where available, or
disable them entirely.

[Thierry]

Hi,

On Tue, Feb 16, 2021 at 04:30:34PM -0800, Matthias Koeppe wrote:
[...]

> For a proposal for packaging of the documentation of Sage itself - please
> see https://trac.sagemath.org/ticket/29868 (pip-installable packages
> sagemath-doc-src, sagemath-doc-inventory, sagemath-doc-html,
> sagemath-doc-pdf) - comments and help with the implementation are welcome
> here too.

Regarding Sage's own documentation, a useful feature, while not related
to the release process, would be to keep online documentation of each
release, that is having:

https://doc.sagemath.org/VERSION/ for each release, and having
https://doc.sagemath.org/current/ pointing to the doc of the last
release.

Currently some links on the web (e.g. on ask.sagemath.org) are outdated
as the discussion does not correspond to the current state of the doc.

Ciao,
Thierry

> Matthias
>
>
> --
> You received this message because you are subscribed to the Google Groups "sage-devel" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/dc6ab03f-2ef2-4ba1-9929-a8061e30dcf6n%40googlegroups.com.

[Matthias Koeppe]

On Wednesday, February 17, 2021 at 12:58:40 PM UTC-8 Thierry (sage-googlesucks@xxx) wrote:

Regarding Sage's own documentation, a useful feature, while not related
to the release process, would be to keep online documentation of each
release, that is having:

https://doc.sagemath.org/VERSION/ for each release, and having
https://doc.sagemath.org/current/ pointing to the doc of the last
release.

+1 

[TB]

The Python docs at https://docs.python.org and Read the Docs, e.g.
https://ipywidgets.readthedocs.io, have a version menu. How did they
configured their Sphinx build or theme layout for that?

[Samuel Lelievre]

2021-02-17 21:22:38 UTC, Matthias Koeppe:

2021-02-17 20:58:40 PM UTC Thierry:

Regarding Sage's own documentation, a useful feature, while not related
to the release process, would be to keep online documentation of each
release, that is having:

https://doc.sagemath.org/VERSION/ for each release, and having
https://doc.sagemath.org/current/ pointing to the doc of the last
release.

+1 

+1

either "current" or "latest" (many projects use "latest")

 

[Matthias Koeppe]

And also for the current beta please.

[Matthias Koeppe]

I have opened https://github.com/sagemath/website/issues/213 ("Versioned Sage documentation")

[Samuel Lelievre]

2021-02-18 16:40:35 UTC, Matthias Koeppe:

And also for the current beta please.

+1