#13679 closed enhancement (fixed)
Build sphinx docs for a single file
Reported by:  jhpalmieri  Owned by:  mvngu 

Priority:  minor  Milestone:  sage6.4 
Component:  documentation  Keywords:  Sphinx 
Cc:  kcrisman, SimonKing, slabbe, tjolivet, okazymyrov, vdelecroix  Merged in:  
Authors:  John Palmieri  Reviewers:  Volker Braun 
Report Upstream:  N/A  Work issues:  Cython files, .sage files 
Branch:  a92dd08 (Commits, GitHub, GitLab)  Commit:  
Dependencies:  Stopgaps: 
Description (last modified by )
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.
Attachments (1)
Change History (23)
comment:1 Changed 9 years ago by
 Cc kcrisman added
comment:2 Changed 9 years ago by
comment:3 Changed 9 years ago by
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.
Changed 9 years ago by
comment:4 Changed 9 years ago by
 Cc SimonKing added
comment:5 Changed 8 years ago by
 Cc slabbe added
comment:6 Changed 8 years ago by
 Cc tjolivet added
comment:7 Changed 8 years ago by
 Milestone changed from sage5.11 to sage5.12
comment:8 Changed 8 years ago by
 Cc okazymyrov added
comment:9 Changed 8 years ago by
 Milestone changed from sage6.1 to sage6.2
comment:10 Changed 8 years ago by
 Branch set to u/jhpalmieri/sphinxsinglefile
 Commit set to a0f7676599b0b4fb72c97c23e015acb478553866
 Description modified (diff)
 Status changed from new to needs_review
 Work issues changed from Cython files to Cython files, .sage files
New commits:
a0f7676  Build documentation for a single Python file

comment:11 Changed 8 years ago by
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.
comment:12 Changed 8 years ago by
 Milestone changed from sage6.2 to sage6.3
comment:14 Changed 7 years ago by
 Status changed from needs_review to needs_work
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
comment:15 Changed 7 years ago by
 Commit changed from a0f7676599b0b4fb72c97c23e015acb478553866 to a92dd08e6f9e36d54bc21217e8c905307122908a
comment:16 Changed 7 years ago by
 Status changed from needs_work to needs_review
This option will now appear in the help message. Also, you can specify the flag o DIR
to write the output to DIR
.
comment:17 Changed 7 years ago by
 Milestone changed from sage6.3 to sage6.4
comment:18 Changed 7 years ago by
 Reviewers set to Volker Braun
 Status changed from needs_review to positive_review
comment:19 Changed 7 years ago by
 Branch changed from u/jhpalmieri/sphinxsinglefile to a92dd08e6f9e36d54bc21217e8c905307122908a
 Resolution set to fixed
 Status changed from positive_review to closed
comment:20 followup: ↓ 21 Changed 7 years ago by
 Commit a92dd08e6f9e36d54bc21217e8c905307122908a deleted
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!
comment:21 in reply to: ↑ 20 Changed 7 years ago by
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).
comment:22 Changed 7 years ago by
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.)
ping: Hello!! There is a patch file here! So, does this code need review? :) Thanks!