The built documentation location

[Kwankyu Lee]

Hi,

As of 10.8.beta2 (perhaps also earlier releases), the built documentation is found in build/sage-distro/src/doc/html/en/reference. The standard location was local/share/doc/sage/html/en/reference.

Is this intended or a bug? Due to the change, the following does not work

$ ./sage
┌────────────────────────────────────────────────────────────────────┐
│ SageMath version 10.8.beta2, Release Date: 2025-09-07              │
│ Using Python 3.13.5. Type "help()" for help.                       │
└────────────────────────────────────────────────────────────────────┘
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Warning: this is a prerelease version, and it may be unstable.     ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
sage: reference()
---------------------------------------------------------------------------
OSError                                   Traceback (most recent call last)
...
OSError: The document 'reference' does not exist.  Please build it
with 'sage -docbuild reference html' and try again.

A related question. To prevent this sort of regression, there is a doctest

      sage: manual()  # indirect doctest, not tested

in src/sage/misc/sagedoc.py. But as you see, the "not tested" tag makes it useless. Why a doctest is "not tested"? 

[Kwankyu Lee]

On Tuesday, September 9, 2025 at 9:58:57 AM UTC+9 Kwankyu Lee wrote:

... in src/sage/misc/sagedoc.py. But as you see, the "not tested" tag makes it useless. Why a doctest is "not tested"? 

To prevent undesirable side effects, such as opening an web browser. 

OK. 

[Dima Pasechnik]

On Mon, Sep 8, 2025 at 7:59 PM Kwankyu Lee <ekwa...@gmail.com> wrote:
>
> Hi,
>
> As of 10.8.beta2 (perhaps also earlier releases), the built documentation is found in build/sage-distro/src/doc/html/en/reference. The standard location was local/share/doc/sage/html/en/reference.
>
> Is this intended or a bug?

it's the location dictated by Meson, to have things built in the build
directory.
In a sage-distro-agnostic setup, there is even no SAGE_LOCAL to speak about.

We can of course create a symbolic link to build/sage-distro/src/doc/html/
from local/share/doc/sage/html/ if needed. Is launching documentation via

sage: reference()

the only place where this matters?

Dima

> Due to the change, the following does not work
>
> $ ./sage
> ┌────────────────────────────────────────────────────────────────────┐
> │ SageMath version 10.8.beta2, Release Date: 2025-09-07 │
> │ Using Python 3.13.5. Type "help()" for help. │
> └────────────────────────────────────────────────────────────────────┘
> ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
> ┃ Warning: this is a prerelease version, and it may be unstable. ┃
> ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
> sage: reference()
> ---------------------------------------------------------------------------
> OSError Traceback (most recent call last)
> ...
> OSError: The document 'reference' does not exist. Please build it
> with 'sage -docbuild reference html' and try again.
>
> A related question. To prevent this sort of regression, there is a doctest
>
> sage: manual() # indirect doctest, not tested
>
> in src/sage/misc/sagedoc.py. But as you see, the "not tested" tag makes it useless. Why a doctest is "not tested"?
>
>

> --
> 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 visit https://groups.google.com/d/msgid/sage-devel/42bbb5e0-d50d-42df-a290-548d45771e56n%40googlegroups.com.

[Kwankyu Lee]

the only place where this matters?

Perhaps all code that references "SAGE_DOC" environment variable would be affected.

[Tobia...@gmx.de]

As of 10.8.beta2 (perhaps also earlier releases), the built documentation is found in build/sage-distro/src/doc/html/en/reference. The standard location was local/share/doc/sage/html/en/reference.

Is this intended or a bug?

The docs are placed in whatever folder you pass under `-o` to the sage_docbuild script. In the case of `make  doc-html` this is indeed some folder under build/sage-distro, but it could be also a completely different directory.

So I don't think there is a reliable way to find out where the built html files are located and thus SAGE_DOC should be avoided if possible (or you should set the env variable manually before starting sage). In the case of `reference`, is there a good reason this is not simply opening https://doc.sagemath.org/ in case SAGE_DOC doesn't point to an existing folder?

[Dima Pasechnik]

On Tue, Sep 9, 2025 at 9:47 AM 'Tobia...@gmx.de' via sage-devel
<sage-...@googlegroups.com> wrote:
>
>
> As of 10.8.beta2 (perhaps also earlier releases), the built documentation is found in build/sage-distro/src/doc/html/en/reference. The standard location was local/share/doc/sage/html/en/reference.
>
> Is this intended or a bug?
>
>
> The docs are placed in whatever folder you pass under `-o` to the sage_docbuild script. In the case of `make doc-html` this is indeed some folder under build/sage-distro, but it could be also a completely different directory.
>
> So I don't think there is a reliable way to find out where the built html files are located and thus SAGE_DOC should be avoided if possible (or you should set the env variable manually before starting sage).

applying

--- a/src/bin/sage-env
+++ b/src/bin/sage-env
@@ -241,6 +241,8 @@ if [ -n "$SAGE_SRC" ]; then
export SAGE_DOC_SRC="$SAGE_SRC/doc"
fi

+export SAGE_DOC="$SAGE_ROOT/build/sage-distro/src/doc"
+
if [ -n "$SAGE_PKG_CONFIG_PATH" ]; then
# set up external pkg-config to look into SAGE_LOCAL/lib/pkgconfig/
# (Sage's pkgconf spkg takes care of this, if installed)

makes

sage: reference()

work. How can one write a doctest to test that this works, is a question.

> In the case of `reference`, is there a good reason this is not simply opening https://doc.sagemath.org/ in case SAGE_DOC doesn't point to an existing folder?
>

> --
> 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 visit https://groups.google.com/d/msgid/sage-devel/fda23be8-f292-4e1e-8d63-32b9010652c9n%40googlegroups.com.

[Kwankyu Lee]

The docs are placed in whatever folder you pass under `-o` to the sage_docbuild script. In the case of `make  doc-html` this is indeed some folder under build/sage-distro, but it could be also a completely different directory.

 

doc is built after sage is built. Why not just put SAGE_DOC under '-o'?

[Kwankyu Lee]

On Tuesday, September 9, 2025 at 11:47:50 PM UTC+9 Tobia...@gmx.de wrote:

 In the case of `reference`, is there a good reason this is not simply opening https://doc.sagemath.org/ in case SAGE_DOC doesn't point to an existing folder?

SAGE_DOC should point to an existing folder if doc was built.

Anyway, the online doc is for version 10.6. I guess the maintainer is having a hard time since his scripts do not work as before... 

[Dima Pasechnik]

On Tue, Sep 9, 2025 at 6:27 PM Kwankyu Lee <ekwa...@gmail.com> wrote:
>
>
>
> On Tuesday, September 9, 2025 at 11:47:50 PM UTC+9 Tobia...@gmx.de wrote:
>
> In the case of `reference`, is there a good reason this is not simply opening https://doc.sagemath.org/ in case SAGE_DOC doesn't point to an existing folder?
>
>
> SAGE_DOC should point to an existing folder if doc was built.

here is a fix I propose: https://github.com/sagemath/sage/pull/40798

>
> Anyway, the online doc is for version 10.6. I guess the maintainer is having a hard time since his scripts do not work as before...
>

> --
> 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 visit https://groups.google.com/d/msgid/sage-devel/62adb459-0479-45fc-b6a5-3cd7d7f229acn%40googlegroups.com.

[Tobia...@gmx.de]

+export SAGE_DOC="$SAGE_ROOT/build/sage-distro/src/doc"

This fixes it only for sage-the-distro, not for anyone else. We really should just remove all those SAGE_xyz variables. For SAGE_DOC this should be relatively simple, since it's essentially only used in src\sage\misc\sagedoc.py and there we could simply open the live website instead of launching our own http server.

  |  doc is built after sage is built. Why not just put SAGE_DOC under '-o'?

It's already falling back to SAGE_DOC if you don't specify '-o'. But that doesn't solve the question why/how sagelib should determine where you (or your distro) will end up installing the documentation. Say on arch, I'm installing the sagemath-doc package which puts it in usr/share/doc/sage. How do you communicate that to sagemath? Another distro might want put it in another folder... We could add a config build variable for sagelib that says "I might install your docs in this place" and then use this as the default for SAGE_DOC. sage-the-distro can then set it to build/sage-distro, while arch sets its to usr/share/doc/sage etc. But all of this sounds rather complicated if you could 009open a webbrowser at https://doc.sagemath.org/ instead.

Scipy for example just says "Documentation is available in the docstrings and online at https://docs.scipy.org/doc/scipy/", and is done with this topic. Since for at least three years they also don't build their docs as pdfs anymore.

   |  Anyway, the online doc is for version 10.6.

We might have talked about this before: what about hosting the final docs also on netlify (with the same github publishing infrastructure we currently have in place for https://doc-develop--sagemath.netlify.app). In my experience, there were no problems with this setup (apart from general issues building the docs) and it's fully automated.

[Kwankyu Lee]

 We really should just remove all those SAGE_xyz variables. 

Why? Do you assume that sage-the-distro is dead?  

  |  doc is built after sage is built. Why not just put SAGE_DOC under '-o'?

It's already falling back to SAGE_DOC if you don't specify '-o'. But that doesn't solve the question why/how sagelib should determine where you (or your distro) will end up installing the documentation.

 '"SAGE_ROOT/local/share/doc" has been the default and I don't see why this should change. 

 

Say on arch, I'm installing the sagemath-doc package which puts it in usr/share/doc/sage. How do you communicate that to sagemath? 

I don't know. Define SAGE_DOC to the non-default location?  Anyway, this is not a new problem. 

A new problem is that now the doc is not installed into the default location defined by SAGE_DOC.

 

[François Bissey]

On 10/09/2025 16:17, Kwankyu Lee wrote:

 We really should just remove all those SAGE_xyz variables. 

Why? Do you assume that sage-the-distro is dead?  

Even if sage-the-distro was dead, those variables are useful.
And if we say it is dead, well, it should go in a more standard location, which at minimum would be $prefix/share/doc and configurable. In Gentoo we want stuff in /usr/share/doc/pkg-name-pkg-version and I have been managing that properly so far, and I certainly want a mechanism to do it in the future and I want it properly documented.
Right now if you are using the Makefile in `src/doc` sage-distro is hard-coded, it has to be changed.

[Dima Pasechnik]

www.sagemath.org is hosted om github Pages, and this makes it quite
easy to upload built docs there.
So this can be automated, say, via
https://github.com/JamesIves/github-pages-deploy-action
(I did use it here:
https://github.com/cddlib/polyhedral_faq/blob/main/.github/workflows/main.yml
- just one file there, but certainly it should be able to do directories)

Dima

>
> --
> 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 visit https://groups.google.com/d/msgid/sage-devel/1b2a078e-4104-4639-87e6-919858977dc4n%40googlegroups.com.

[Tobia...@gmx.de]

On Wednesday, September 10, 2025 at 12:17:27 PM UTC+8 Kwankyu Lee wrote:

 We really should just remove all those SAGE_xyz variables. 

Why? Do you assume that sage-the-distro is dead?  

I do think it's close to dead, but that's not the point. The reason why SAGE_xyz should not be used is because they mostly encode false and outdated assumptions. To give a few examples:

SAGE_SRC: There is no source folder after you installed; in particular you should be able to delete the source folder later without breaking anything

SAGE_ROOT: Same.

SAGE_PKGS: Doesn't even make sense outside of sage-the-distro.

SAGE_VENV: Should always be the currently activated venv and it's better to use importlib to find stuff there

SAGE_SHARE: Also doesn't make sense outside of sage-the-distro. Instead of looking for stuff there at runtime, you should try to find your resources at build time.

Say on arch, I'm installing the sagemath-doc package which puts it in usr/share/doc/sage. How do you communicate that to sagemath? 

I don't know. Define SAGE_DOC to the non-default location?  Anyway, this is not a new problem.

That's my point. There is universally correct "default location", not even within sage-the-distro, so you have to set SAGE_DOC after you build the docs to tell sagelib where they are installed.

  In Gentoo we want stuff in /usr/share/doc/pkg-name-pkg-version and I have been managing that properly so far, and I certainly want a mechanism to do it in the future

meson setup build

meson compile -C build doc-html

cp -r build/src/doc/html usr/share/doc/sage-$VERSION

As for example done on arch: https://github.com/gripped/archpkgbuilds/blob/master/extra/sagemath-doc/PKGBUILD

How do you currently set SAGE_DOC at runtime in Gentoo?

 

[Kwankyu Lee]

...

SAGE_SHARE: Also doesn't make sense outside of sage-the-distro. Instead of looking for stuff there at runtime, you should try to find your resources at build time.

They all make sense in sage-the-distro. 

 

 ... so you have to set SAGE_DOC after you build the docs to tell sagelib where they are installed.

In sage-the-distro, the doc is installed by default to the location set by SAGE_DOC.

[Michael Orlitzky]

On 2025-09-10 16:30:09, François Bissey wrote:
> Even if sage-the-distro was dead, those variables are useful.
> And if we say it is dead, well, it should go in a more standard
> location, which at minimum would be $prefix/share/doc and configurable.
> In Gentoo we want stuff in /usr/share/doc/pkg-name-pkg-version and I
> have been managing that properly so far, and I certainly want a
> mechanism to do it in the future and I want it properly documented.

I think the closest thing to The Right Way would be for meson to
support --docdir, and then for everyone to pass it their favorite
directory:

https://github.com/mesonbuild/meson/issues/825

Our build system would then not just build the docs, but also install
them (to the given location). In the meantime I guess we could fake
this with a custom option of the same name, e.g.

$ meson setup -Ddocdir=/path/to/docs ...

[Dima Pasechnik]

and SAGE_DOC is set, completely disjointly, in two different places:
in sage.env and in src/bin/sage-env
So it's does not make sense to talk about something set by SAGE_DOC,
as it looks as some convenience
value, nothing cut in stone or anything.

Whatever sagelib does, what it is installing where, should be
described using the standard python conventions,
(pyproject.toml etc)
not by some semi-random bunch of variables coming from somewhere vague.

>
> --
> 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 visit https://groups.google.com/d/msgid/sage-devel/2c555dfb-7db4-4489-91f6-405cbef5507dn%40googlegroups.com.

[François Bissey]

On 10/09/2025 20:51, 'Tobia...@gmx.de' via sage-devel wrote:

meson setup build

meson compile -C build doc-html

cp -r build/src/doc/html usr/share/doc/sage-$VERSION

As for example done on arch: https://github.com/gripped/archpkgbuilds/blob/master/extra/sagemath-doc/PKGBUILD

How do you currently set SAGE_DOC at runtime in Gentoo?

 

A long time ago before it was a thing in sage I had made a file similar to what is now sage/env.py.
These days, I set it at build time in the file that becomes: sage/config.py which defines all those things that are different in gentoo compared to some other environments.
You mention several SAGE_* variable, I have fought for several years so that SAGE_ROOT would never be used at runtime and only be a build time thing, I will not miss it. I also worked and got that SAGE_SRC would just be the sage python module path at runtime by default (prefix/lib/python-3.xx/site-packages/sage/) - it was mostly important for doctesting.
I will not miss it either. By the way how do you run tests in the meson setup?

Stuff that I currently set:
SAGE_SHARE   = "/usr/share/sage"
SAGE_DOC     = "/usr/share/doc/sagemath-doc-9999"

GAP_ROOT_PATHS  = "/usr/lib64/gap;/usr/share/gap"
THEBE_DIR    = "/usr/share/thebe"
JMOL_DIR     = "/usr/share/sage-jmol-bin/lib"
MATHJAX_DIR  = "/usr/share/mathjax"
MTXLIB       = "/usr/share/meataxe"
SINGULARPATH = "/usr/share/singular"
PPLPY_DOCS   = "/usr/share/doc/pplpy-0.8.10-r1/html"
THREEJS_DIR  = "/usr/share/sage/threejs"

LIE_INFO_DIR = "/usr/share/lie"

MAXIMA       = "maxima -l ecl"

# Names or paths of the 4ti2 executables
FOURTITWO_HILBERT = "hilbert"
FOURTITWO_MARKOV = "markov"
FOURTITWO_GRAVER = "graver"
FOURTITWO_ZSOLVE = "zsolve"
FOURTITWO_QSOLVE = "qsolve"
FOURTITWO_RAYS = "rays"
FOURTITWO_PPI = "ppi"
FOURTITWO_CIRCUITS = "circuits"
FOURTITWO_GROEBNER = "groebner"

The last group was added because debian and derivatives prefix all the 4ti2 executable with 4ti2 - which is not universal across distro, getting rid of this fully at build time instead of having to set it (even if automated already) would be nice.

François