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: |
Description (last modified by )
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: ↓ 3 Changed 4 years ago by
- Cc jdemeyer added
comment:2 Changed 4 years ago by
- Description modified (diff)
comment:3 in reply to: ↑ 1 Changed 4 years ago by
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: ↓ 5 Changed 4 years ago by
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: ↓ 6 Changed 4 years ago by
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
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!
@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: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?