How to rebuild documentation

[Albert Yao]

Hi all,

I currently have sage 10.8.beta6 installed. I tried running "sage --docbuild tutorial html" in the sage-dev environment, but when I run that line, it returns "unrecognized arguments: --docbuild html". What should I do?

Also, I am following this guide: https://doc-release--sagemath.netlify.app/html/en/developer/sage_manuals#chapter-sage-manuals

If you can help, that would be great!

Albert

[Dima Pasechnik]

The current way to build the html docs is

"make doc-html"

As far as I understand, there is currently no way to build only a part of the docs.

HTH

Dmitrii

--
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/2958b2e3-784e-4d53-a47a-d1be974772c5n%40googlegroups.com.

[Kwankyu Lee]

This

sage --docbuild en/tutorial html

should work. But this seems to be currently broken. 

[Kwankyu Lee]

This

sage --docbuild -D

should work. This is also terribly broken

[Albert Yao]

Yea, it seems to be broken for me. Is there a way I can test my documentation?

[Albert Yao]

Is there I can test my documentation for my method without rebuilding the docs?

On Friday, October 17, 2025 at 5:07:46 PM UTC-4 Kwankyu Lee wrote:

[Albert Yao]

This is what it gives me after I trie using the command sage --docbuild -D

usage: sage [-h] [-v] [-q] [--simple-prompt] [-V] [-n [{jupyter,jupyterlab}]]

            [-c [COMMAND]]

            [file]

sage: error: unrecognized arguments: --docbuild -D

[Dima Pasechnik]

On Fri, Oct 17, 2025 at 6:13 PM Albert Yao <albert...@gmail.com> wrote:

Is there I can test my documentation for my method without rebuilding the docs?

you can certainly reduce the amount of rebuild by modifying src/doc/meson.build

So you can easily see how to leave only one language in

(look at all these subdir('el') in the beginning), 

and build either only the reference manual, or "the other documents"

(look at how aliases are set at the bottom)

As you see, it's just gets the lists of documents from sage_docbuild interface,

without doing anything more detailed. I imagine one can get smaller lists of docs files to rebuild,

but I don't know how.

Yes, it's written in "meson language" (much easier than m4 and shell, but, well...)

with calls to Python ("py") 

https://mesonbuild.com/Reference-manual.html

 

On Friday, October 17, 2025 at 5:07:46 PM UTC-4 Kwankyu Lee wrote:

This

sage --docbuild en/tutorial html

should work. But this seems to be currently broken. 

--

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/bd6a1f76-a4d8-4fb4-b23a-7f8229e433f5n%40googlegroups.com.

[Kwankyu Lee]

I touched src/sage/structure/factory.pyx, and wanted to rebuild only the relevant part of the reference manual. This is I got:

$ sage --docbuild reference/structure html
[structure] inventory <https://ipywidgets.readthedocs.io/en/stable/> contains multiple definitions for std:label:examples/Widget Layout.ipynb#display
[structure] WARNING: failed to reach any of the inventories with the following issues:
[structure] intersphinx inventory '/Users/kwankyu/GitHub/sage-dev/local/share/doc/sage/inventory/en/reference/objects.inv' not readable due to FileNotFoundError: [Errno 2] No such file or directory: '/Users/kwankyu/GitHub/sage-dev/local/share/doc/sage/inventory/en/reference/objects.inv'
[structure] WARNING: failed to reach any of the inventories with the following issues:
[structure] intersphinx inventory '/Users/kwankyu/GitHub/sage-dev/local/share/doc/sage/inventory/en/reference/structure/objects.inv' not readable due to FileNotFoundError: [Errno 2] No such file or directory: '/Users/kwankyu/GitHub/sage-dev/local/share/doc/sage/inventory/en/reference/structure/objects.inv'
[structure] no targets are out of date.
[structure] The HTML pages are in local/share/doc/sage/html/en/reference/structure.
Error building the documentation.
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "/Users/kwankyu/GitHub/sage-dev/src/sage_docbuild/__main__.py", line 552, in <module>
    sys.exit(main())
             ~~~~^^
  File "/Users/kwankyu/GitHub/sage-dev/src/sage_docbuild/__main__.py", line 548, in main
    build()
    ~~~~~^^
  File "/Users/kwankyu/GitHub/sage-dev/src/sage_docbuild/builders.py", line 669, in _wrapper
    getattr(DocBuilder, build_type)(self, *args, **kwds)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^
  File "/Users/kwankyu/GitHub/sage-dev/src/sage_docbuild/builders.py", line 142, in f
    runsphinx()
    ~~~~~~~~~^^
  File "/Users/kwankyu/GitHub/sage-dev/src/sage_docbuild/sphinxbuild.py", line 324, in runsphinx
    sys.stderr.raise_errors()
    ~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/Users/kwankyu/GitHub/sage-dev/src/sage_docbuild/sphinxbuild.py", line 255, in raise_errors
    raise OSError(self._error)
OSError: WARNING: failed to reach any of the inventories with the following issues:

The command "sage --docbuild" is an essential tool for any developer working on sagelib. It should work.