Install built doc to SAGE_DOC #40807

kwankyu · 2025-09-12T03:58:11Z

This is a solution for https://groups.google.com/g/sage-devel/c/IVo1EI33CyU, alternative to #40798.

With this PR

make doc-html

installs the built doc to the expected location (set by SAGE_DOC). The same with

make doc-pdf

📝 Checklist

The title is concise and informative.
The description explains in detail what this PR is about.
I have linked a relevant issue or discussion.
I have created tests covering the changes.
I have updated the documentation and checked the documentation preview.

⌛ Dependencies

github-actions · 2025-09-12T05:04:17Z

Documentation preview for this PR (built with commit f7cafd3; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

antonio-rojas · 2025-09-13T07:13:34Z

IMO it would be better to do this at the meson level (with install-doc-{html,pdf} targets) and then Makefile would just call these targets. That way, other distributions could also make use of it instead of manually copying docs as it is done now.

That being said, this change only affects sage-the-distro so I have no objection as a temporary stopgap.

tobiasdiez · 2025-09-14T02:31:58Z

src/sage_docbuild/builders.py

@@ -145,11 +145,6 @@ def f(self, *args, **kwds):
            if build_options.ABORT_ON_ERROR:
                raise Exception("Non-exception during docbuild: %s" % (e,), e)

-        if type == 'latex':


why remove this? The files are in those places, or not?

They show the absolute path to the built docs in the meson build directory. So they do not match with the install directory now, at least for sage-the-distro. They look redundant and misleading.

I guess the same is true in other scenarios. Do they show the correct directory for you? Then I may restore the logging.

Do they show the correct directory for you? Then I may restore the logging.

Yes, they show the correct build directory (even for users of sage-the-distro).

It is correct "build directory". But users should be notified the correct "install directory".

Sphinx already displays the relative paths to the built files. The additional display of the absolute paths to the "build directory" seems redundant and misleading at least for sage-the-distro users.

If the absolute paths to the build directory are still useful to users in other environment, I am okay to restore the deleted lines. Let me know.

I may also add an echo command in the Makefile to display the install directory after copying.

If the absolute paths to the build directory are still useful to users in other environment, I am okay to restore the deleted lines. Let me know.

Yes please restore it. There is no such thing as an install directory in the context of the sage_docbuild commands.

Okay.

By the way,

$ sage --docbuild en/tutorial html [tutorial ] building [html]: targets for 23 source files that are out of date [tutorial ] updating environment: [new config] 23 added, 0 changed, 0 removed [tutorial ] Extension error! ... [tutorial ] * matplotlib.sphinxext.plot_directive (3.10.5) [tutorial ] * jupyter_sphinx (0.5.3) [tutorial ] * furo (2024.07.18) [tutorial ] * sphinx_basic_ng (1.0.0.beta2) [tutorial ] Traceback [tutorial ] ========= [tutorial ] File "/Users/kwankyu/GitHub/sage-dev/local/var/lib/sage/venv-python3.13/lib/python3.13/site-packages/jupyter_sphinx/utils.py", line 15, in blank_nb [tutorial ] raise ExtensionError("Unable to find kernel", orig_exc=e) [tutorial ] sphinx.errors.ExtensionError: Unable to find kernel (exception: No such kernel named sagemath) [tutorial ] The full traceback has been saved in: [tutorial ] /var/folders/t2/sj0m9bz56rlcy7kvx_hr4jjw0000gn/T/sphinx-err-lq7i4i2d.log [tutorial ] To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks! [tutorial ] Please also report this if it was a user error, so that a better error message can be provided next time. Build finished. The built documents can be found in /Users/kwankyu/GitHub/sage-dev/local/share/doc/sage/html/en/tutorial.

Does the command work for you?

I restored the logging. For Makefile, the install directory is printed after copying.

Thanks, and yes, it's finding the kernel for me.

tobiasdiez · 2025-09-14T02:32:44Z

src/doc/Makefile


 doc-html:
 	meson compile -C ../../build/sage-distro doc-html
+	mkdir -p $(SAGE_DOC)
+	cp -rf ../../build/sage-distro/src/doc/html $(SAGE_DOC)


where does SAGE_DOC points to on your system, i.e. where do those docs end up in?

For sage-the-distro, it is local/share/doc at sage root by default. The Makefile runs after environment variables for sage-the-distro are setup.

kwankyu · 2025-09-14T06:44:21Z

IMO it would be better to do this at the meson level (with install-doc-{html,pdf} targets) and then Makefile would just call these targets. That way, other distributions could also make use of it instead of manually copying docs as it is done now.

Yes. Then src/doc/meson.build should be modified.

That being said, this change only affects sage-the-distro so I have no objection as a temporary stopgap.

Yes.

kwankyu · 2025-09-15T22:48:00Z

Strangely, doctrees directory is also copied, in my testing. Let me fix this.

kwankyu · 2025-09-16T02:29:28Z

There must have been some confusion on my side. I tested again. It works well.

Ready to go.

kwankyu marked this pull request as ready for review September 12, 2025 04:22

github-actions bot added the s: needs review label Sep 12, 2025

kwankyu mentioned this pull request Sep 12, 2025

fix SAGE_DOC variables #40798

Closed

5 tasks

tobiasdiez reviewed Sep 14, 2025

View reviewed changes

kwankyu added 2 commits September 15, 2025 17:07

Install built doc to SAGE_DOC

c984a3a

Print the doc install directory only for make

f7cafd3

kwankyu force-pushed the p/fix-doc-location branch from 13be91e to f7cafd3 Compare September 15, 2025 08:29

kwankyu added s: needs work and removed s: needs review labels Sep 15, 2025

kwankyu marked this pull request as draft September 15, 2025 22:47

github-actions bot removed the s: needs work label Sep 15, 2025

kwankyu marked this pull request as ready for review September 16, 2025 02:28

github-actions bot added the s: needs review label Sep 16, 2025

kwankyu added the c: documentation label Sep 16, 2025

Uh oh!

Install built doc to SAGE_DOC #40807

Are you sure you want to change the base?

Install built doc to SAGE_DOC #40807

Uh oh!

Conversation

kwankyu commented Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📝 Checklist

⌛ Dependencies

Uh oh!

github-actions bot commented Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

antonio-rojas commented Sep 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kwankyu commented Sep 14, 2025

Uh oh!

kwankyu commented Sep 15, 2025

Uh oh!

kwankyu commented Sep 16, 2025

Uh oh!

Uh oh!

kwankyu commented Sep 12, 2025 •

edited

Loading

github-actions bot commented Sep 12, 2025 •

edited

Loading