#13679 closed enhancement (fixed)
Build sphinx docs for a single file
Reported by: | jhpalmieri | Owned by: | mvngu |
---|---|---|---|
Priority: | minor | Milestone: | sage-6.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 10 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 9 years ago by
- Cc slabbe added
comment:6 Changed 9 years ago by
- Cc tjolivet added
comment:7 Changed 9 years ago by
- Milestone changed from sage-5.11 to sage-5.12
comment:8 Changed 9 years ago by
- Cc okazymyrov added
comment:9 Changed 8 years ago by
- Milestone changed from sage-6.1 to sage-6.2
comment:10 Changed 8 years ago by
- Branch set to u/jhpalmieri/sphinx-single-file
- 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 sage-6.2 to sage-6.3
comment:14 Changed 8 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 8 years ago by
- Commit changed from a0f7676599b0b4fb72c97c23e015acb478553866 to a92dd08e6f9e36d54bc21217e8c905307122908a
comment:16 Changed 8 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 8 years ago by
- Milestone changed from sage-6.3 to sage-6.4
comment:18 Changed 8 years ago by
- Reviewers set to Volker Braun
- Status changed from needs_review to positive_review
comment:19 Changed 8 years ago by
- Branch changed from u/jhpalmieri/sphinx-single-file to a92dd08e6f9e36d54bc21217e8c905307122908a
- Resolution set to fixed
- Status changed from positive_review to closed
comment:20 follow-up: ↓ 21 Changed 8 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 8 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 8 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!