Skip to content

Use Meson targets to build the manuals - #42646

Merged
vbraun merged 4 commits into
sagemath:developfrom
cxzhong:codex/fix-41887-docbuild-docs
Sep 24, 2026
Merged

vbraun merged 4 commits into
sagemath:developfrom
cxzhong:codex/fix-41887-docbuild-docs

Conversation

@cxzhong

@cxzhong cxzhong commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

This updates the documentation build instructions for editable pip installs.
The pip-installed sage command does not expose the legacy --docbuild
option, so installing pkgs/sage-docbuild separately does not provide the
documented workflow.

The documentation now:

  • uses the Meson doc-html and doc-pdf targets for complete builds;
  • documents the target naming scheme for individual manuals;
  • explains how to locate the build/cpXY Meson build directory;
  • updates the installation guide, developer guide, FAQ, Makefile comments,
    and latex_macros.py guidance consistently; and
  • adds an HTML/PDF-compatible "Building the manuals" section to the
    editable-install walkthrough.

This lets contributors rebuild documentation without relying on a Sage
command-line option that is unavailable in the editable pip workflow.

Fixes #41887.

Validation

  • git diff --check
  • verified all documented Meson target names with meson introspect
  • built the Developer Guide, FAQ, and Installation Guide HTML successfully
  • generated the Installation Guide LaTeX successfully, including the new
    section label; final PDF compilation was blocked by missing
    luaotfload-main and luatex85.sty components in the local TeX Live
    installation

📝 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. (Documentation-only change.)
  • I have updated the documentation and checked the documentation preview.

⌛ Dependencies

None.

@github-actions

github-actions Bot commented Aug 9, 2026 •

Copy link
Copy Markdown

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

@cxzhong
cxzhong marked this pull request as ready for review August 11, 2026 01:43
@cxzhong
cxzhong requested a review from orlitzky August 13, 2026 17:20
@orlitzky

Copy link
Copy Markdown
Contributor

Thanks for doing this, we are overdue to replace all of this old incorrect documentation, but the review should be left up to someone who actually uses pip or the sage distro.

@cxzhong

cxzhong commented Aug 15, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for doing this, we are overdue to replace all of this old incorrect documentation, but the review should be left up to someone who actually uses pip or the sage distro.

I have checked this in conda. maybe someone need to check this in sage-the-distro

@cxzhong
cxzhong requested a review from tobiasdiez August 16, 2026 04:00

@tobiasdiez tobiasdiez left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot! Ideally it would be just "run sphinx" but until we are there, this is good enough.

Cannot say if it works for the sage-the-distro people....

Comment thread src/doc/en/installation/source.rst Outdated
$ pip install -Ceditable-verbose=true -Csetup-args="-Dbuild-docs=False" --no-build-isolation --editable .


.. _section-building-manuals-pip:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if the duplication is worth. I would either replace it by a link to the sage_manuals docs or at least move it down to be just before the "background info".

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you check this again? I have checked the sage-the-distro

@orlitzky

Copy link
Copy Markdown
Contributor

@trevorkarn pointed out on sage-devel that the error at https://github.com/sagemath/sage/blob/develop/src/sage/misc/sagedoc.py#L1633 needs an update too

@cxzhong
cxzhong force-pushed the codex/fix-41887-docbuild-docs branch from aefcca7 to e745485 Compare September 12, 2026 07:30
.. code-block:: console

$ sage --docbuild tutorial html
$ meson compile -C builddir doc-html-other-en-tutorial

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
$ meson compile -C builddir doc-html-other-en-tutorial
$ meson compile -C <builddir> doc-html-other-en-tutorial

# documentation), and look at the resulting tex file in
# SAGE_DOC/latex/en/tutorial. The preamble should contain
# To see the results of this, run
# 'meson compile -C builddir doc-pdf-other-en-tutorial', where builddir is

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# 'meson compile -C builddir doc-pdf-other-en-tutorial', where builddir is
# `meson compile -C <builddir> doc-pdf-other-en-tutorial`, where `<builddir>` is

@trevorkarn

trevorkarn commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

I have some additional suggested changes available on https://github.com/trevorkarn/sage/tree/codex/fix-41887-docbuild-docs. @cxzhong, do you have any thoughts on those? The point is to fix the call to manual() for editable builds.

@trevorkarn

Copy link
Copy Markdown
Contributor

Since the previous instructions are broken, this seems high priority to me to get merged before 10.10 is released. I personally would approve these changes even without any of the suggestions I've added, so that we can get closer to an accurate documentation, even if it is not perfect.

@vbraun
vbraun merged commit 0b6db6d into sagemath:develop Sep 24, 2026
45 of 47 checks passed
@trevorkarn

Copy link
Copy Markdown
Contributor

Thanks @vbraun! @cxzhong the changes I suggested are now the content of #42854

@cxzhong
cxzhong deleted the codex/fix-41887-docbuild-docs branch October 2, 2026 04:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

--docbuild command not being recognized by sage

5 participants