Opened 7 years ago

Closed 5 years ago

Last modified 5 years ago

#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) Commit:
Dependencies: Stopgaps:

Description (last modified by 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.

Attachments (1)

trac_13679-single-file.patch​ (4.9 KB) - added by jhpalmieri 6 years ago.

Download all attachments as: .zip

Change History (23)

comment:1 Changed 7 years ago by kcrisman

  • Cc kcrisman added

comment:2 Changed 6 years ago by knsam

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

comment:3 Changed 6 years ago by jhpalmieri

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 6 years ago by jhpalmieri

comment:4 Changed 6 years ago by SimonKing

  • Cc SimonKing added

comment:5 Changed 6 years ago by slabbe

  • Cc slabbe added

comment:6 Changed 6 years ago by tjolivet

  • Cc tjolivet added

comment:7 Changed 6 years ago by jdemeyer

  • Milestone changed from sage-5.11 to sage-5.12

comment:8 Changed 6 years ago by okazymyrov

  • Cc okazymyrov added

comment:9 Changed 5 years ago by vbraun_spam

  • Milestone changed from sage-6.1 to sage-6.2

comment:10 Changed 5 years ago by jhpalmieri

  • 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:

​a0f7676Build documentation for a single Python file

comment:11 Changed 5 years ago by jhpalmieri

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 5 years ago by vbraun_spam

  • Milestone changed from sage-6.2 to sage-6.3

comment:13 Changed 5 years ago by vdelecroix

  • Cc vdelecroix added

cc me...

comment:14 Changed 5 years ago by vdelecroix

  • 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 5 years ago by git

  • Commit changed from a0f7676599b0b4fb72c97c23e015acb478553866 to a92dd08e6f9e36d54bc21217e8c905307122908a

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

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

comment:16 Changed 5 years ago by jhpalmieri

  • 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 5 years ago by vbraun_spam

  • Milestone changed from sage-6.3 to sage-6.4

comment:18 Changed 5 years ago by vbraun

  • Reviewers set to Volker Braun
  • Status changed from needs_review to positive_review

comment:19 Changed 5 years ago by vbraun

  • 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: Changed 5 years ago by nthiery

  • 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 5 years ago by kcrisman

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 5 years ago by jhpalmieri

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

Note: See TracTickets for help on using tickets.