Documentation in additional format

[aikrahguzar]

Problem Description

I was looking to build sage documentation in a way that I can work easily with in Emacs. The page https://doc.sagemath.org/html/en/developer/sage_manuals.html#building-the-manuals states that

Output formats: All output formats supported by Sphinx (e.g. pdf) can be used in Sage. See http://www.sphinx-doc.org/builders.html.

However,

sage --docbuild reference texinfo

results in an error,

Error building the documentation.
sage_docbuild.utils.RemoteException: 
"""
Traceback (most recent call last):
  File "/nix/store/3nvsbibp4pdxys5svxvynq343qyv1x7f-python3-3.11.9-env/lib/python3.11/site-packages/sage_docbuild/utils.py", line 211, in run_worker
    result = target(task)
             ^^^^^^^^^^^^
  File "/nix/store/3nvsbibp4pdxys5svxvynq343qyv1x7f-python3-3.11.9-env/lib/python3.11/site-packages/sage_docbuild/builders.py", line 98, in build_ref_doc
    getattr(ReferenceSubBuilder(doc, lang), format)(*args, **kwds)
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'ReferenceSubBuilder' object has no attribute 'texinfo'
"""

And,

sage --docbuild -F

tell me that,

FORMATs:
    html        pdf         changes     htmlhelp    inventory   json        
    latex       linkcheck   pickle      web

so texinfo is probably not supported.

However, it would be nice to support it. I can run sphinx-build -M info /path/to/doc/en/references outputdir, but that doesn't build a complete manual since it doesn't process the nested directories.

Is there a reasonable way to build an info manual out of sage documentation? With some pointers I can look into it myself.

Proposed Solution

A way to build an info manual using sage --docbuild.

Alternatives Considered

An alternative is to use the devhelp format. Since Emacs has packages that support that. However, passing devhelp as the format results in the same error as texinfo.

Additional Information

No response

Is there an existing issue for this?

• I have searched the existing issues for a bug report that matches the one I want to file, without success.

[mkoeppe]

PR to add support for additional formats would be welcome. I think src/sage_docbuild/builders.py is the file to work on.

[aikrahguzar]

Is there a way to run sage_docbuild without building all of sage? I have run into issues building sage from source, see #38424

The repository checkout has a sage executable but

./sage --docbuild reference

complains that,

sage/local/var/lib/sage/venv-python3.12.4/bin/python3: No module named sage_docbuild

[aikrahguzar]

I have managed to install sage and I am trying to build html documentation to test the waters. Some observations:

1. It seems like

   ./sage --docbuild reference inventory
   

   is a requirement for building other kind of documentation? Without it there are lot of warnings about missing inventories. But some a lot of warning missing inventories cause html build to fail.

2. Building inventories fails with due to an include in sage/src/doc/en/reference/repl/options.rst

   .. literalinclude:: options.txt
   

   while there is no options.txt in sage/src/doc/en/reference/repl/. Removing this line makes inventories to build successfully, but I think this file should be there?

3. After building inventory, html docs can be built successfully.

[mantepse]

See #21734 for an old attempt.

I would be extremely grateful for that!

[aikrahguzar]

See #21734 for an old attempt.

I would be extremely grateful for that!

I tried searching for a previous issue but I didn't find it. Since the other issue has many more details, I will close this one comment on the other one.