Build sphinx docs for a single file

[jhpalmieri]

The patch here implements

sage --docbuild file=/path/to/foo.py TYPE

where TYPE may be any of the standard documentation types (e.g., html or pdf). This lets you build the docs for a file inside or outside the Sage library. It doesn't work for .sage or .pyx files right now, only .py files.

CC: @kcrisman @simon-king-jena @seblabbe @sagetrac-tjolivet @sagetrac-okazymyrov @videlec

Component: documentation

Keywords: Sphinx

Work Issues: Cython files, .sage files

Author: John Palmieri

Branch: a92dd08

Reviewer: Volker Braun

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

[KPanComputes]

comment:2

ping: Hello!! There is a patch file here! So, does this code need review? :) Thanks!

[jhpalmieri]

comment:3

Well, it doesn't work for .pyx files, and I think that should be fixed before it's ready for review. When I wrote the original patch, I didn't spend a lot of time working on it, so there are probably other flaws as well. You can certainly test it out and report the results here.

[simon-king-jena]

comment:4

Attachment: trac_13679-single-file.patch.gz

[jhpalmieri]

New commits:

a0f7676

Build documentation for a single Python file

[jhpalmieri]

Changed work issues from Cython files to Cython files, .sage files

[jhpalmieri]

Branch: u/jhpalmieri/sphinx-single-file

[jhpalmieri]

Commit: a0f7676

[jhpalmieri]

comment:11

It would be nice if this worked for .pyx or .sage files, but I think it could be reviewed as is, and merged if it's okay. Then later someone can add the functionality for .pyx or .sage files.

[videlec]

comment:13

cc me...

[videlec]

comment:14

Hi there,

The option does not appear within sage -docbuild --help but it should!

Another minor question: it is a bit annoying that the resulting file belongs to $HOME/.sage/docbuild/output/$NAME_OF_THE_FILE/output/html. Is it possible to do otherwise?

This is a really amazing gadget!

Vincent

[sagetrac-git]

Changed commit from a0f7676 to a92dd08

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

017dad0	Merge branch 'u/jhpalmieri/sphinx-single-file' of git://trac.sagemath.org/sage into develop
a92dd08	Sphinx single-file: more documentation, option to save output elsewhere

[jhpalmieri]

comment:16

This option will now appear in the help message. Also, you can specify the flag -o DIR to write the output to DIR.

[vbraun]

Reviewer: Volker Braun

[vbraun]

Changed branch from u/jhpalmieri/sphinx-single-file to a92dd08

[nthiery]

comment:20

I just discovered this gadget. Yeah! Finally! I have been dreaming of this for a while. Indeed, I write my course notes and work sheets in ReST, and my workflow to convert them to html is, err, painful.

I am just missing one feature: having it work on .rst files as well. Would it be hard?

Thanks!

[nthiery]

Changed commit from a92dd08 to none

[kcrisman]

comment:21

I am just missing one feature: having it work on .rst files as well. Would it be hard?

You could check out the documentation for sage -sws2rst where it tells how to convert the rst files to actual documentation using Sphinx; maybe that will give you an idea of how to do it easily with this (it's been a while since I looked at it).

[jhpalmieri]

comment:22

sage -sws2txt is not a bad first draft for this. Maybe some modification of that script would do what you want. (It seems to produce html, not txt, despite the name. I guess that's consistent with its documentation.)