Extend Sage doc builder so that it can be used for third party packages

[simon-king-jena]

Motivated by #24447 (building cvxopt's doc) and by my own hope to facilitate building the documentation of my group cohomology spkg, I suggest extending Sage's framework for building documentation, so that it can be used outside the Sage src tree.

In other words,

sage -docbuild --output=<outpath> --src=<srcpath> <html/pdf/...>

should go to <srcpath> (which may be a single file or a folder), try to build the docs there (of course under the assumption that the doc format is the same as, say, in SAGE_ROOT/src/doc/en/reference/), and install the documentation in <outpath>.

CC: @jdemeyer

Component: documentation

Keywords: docbuild

Issue created by migration from https://trac.sagemath.org/ticket/24448

[simon-king-jena]

comment:1

@jdemeyer, if I understand correctly you authored much of the current docbuilder.

From the information provided by sage -docbuild --help, I expected the following to do at least something:

./sage -docbuild /home/king/Projekte/coho/coho-3.0-devel/src/pGroupCohomology/cochain.pyx --output=/home/king/Projekte/coho/documentation/

However, it just prints the help, but doesn't tell what is wrong.

Can you explain to me what should be done instead, and where to look for in order to implement something that works as in the ticket description?

[jdemeyer]

comment:3

Replying to @simon-king-jena:

@jdemeyer, if I understand correctly you authored much of the current docbuilder.

That is not actually true. I worked more on the introspection/autodoc aspects of the documentation, not on the build process.

[jdemeyer]

Replying to @simon-king-jena:

I suggest extending Sage's framework for building documentation, so that it can be used outside the Sage src tree.

I would rather do the converse: use the standard existing tools to build the Sage documentation, which can also be used by other packages independent of Sage.

Why can't you use plain Sphinx to build the cvxopt documentation?

[simon-king-jena]

comment:5

Replying to @jdemeyer:

Replying to @simon-king-jena:

I suggest extending Sage's framework for building documentation, so that it can be used outside the Sage src tree.

I would rather do the converse: use the standard existing tools to build the Sage documentation, which can also be used by other packages independent of Sage.

Why can't you use plain Sphinx to build the cvxopt documentation?

Is Sphinx part of the Sage distribution? Then I guess one should simply uncomment the commented-out code in cvxopt's spkg-install.

[simon-king-jena]

comment:6

Replying to @simon-king-jena:

Replying to @jdemeyer:

Replying to @simon-king-jena:

I suggest extending Sage's framework for building documentation, so that it can be used outside the Sage src tree.

I would rather do the converse: use the standard existing tools to build the Sage documentation, which can also be used by other packages independent of Sage.

Why can't you use plain Sphinx to build the cvxopt documentation?

Is Sphinx part of the Sage distribution?

I just see that it is a standard package. Alright then: Make cvxopt depend on sphinx and allow the documentation to be built!