Opened 4 years ago

Last modified 4 years ago

#24448 new enhancement

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

Reported by: SimonKing Owned by:
Priority: major Milestone: sage-8.2
Component: documentation Keywords: docbuild
Cc: jdemeyer Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges

Description (last modified by SimonKing)

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>.

Change History (6)

comment:1 follow-up: Changed 4 years ago by SimonKing

  • Cc jdemeyer added

@Jeroen, 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?

comment:2 Changed 4 years ago by SimonKing

  • Description modified (diff)

comment:3 in reply to: ↑ 1 Changed 4 years ago by jdemeyer

Replying to SimonKing:

@Jeroen, 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.

comment:4 in reply to: ↑ description ; follow-up: Changed 4 years ago by jdemeyer

Replying to SimonKing:

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?

comment:5 in reply to: ↑ 4 ; follow-up: Changed 4 years ago by SimonKing

Replying to jdemeyer:

Replying to SimonKing:

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.

comment:6 in reply to: ↑ 5 Changed 4 years ago by SimonKing

Replying to SimonKing:

Replying to jdemeyer:

Replying to SimonKing:

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!

Note: See TracTickets for help on using tickets.