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 ...