Opened 13 years ago
Closed 13 years ago
#6820 closed enhancement (fixed)
Easy command-line access to HTML documentation and docstrings
Reported by: | John Palmieri | Owned by: | tba |
---|---|---|---|
Priority: | minor | Milestone: | sage-4.3.1 |
Component: | documentation | Keywords: | documentation |
Cc: | Mitesh Patel | Merged in: | sage-4.3.1.alpha0 |
Authors: | John Palmieri, Mitesh Patel | Reviewers: | Mitesh Patel, John Cremona, John Palmieri |
Report Upstream: | N/A | Work issues: | |
Branch: | Commit: | ||
Dependencies: | Stopgaps: |
Description (last modified by )
The attached patch introduces the command browse_sage_doc
. It lets you do the following from either the command-line or the notebook:
browse_sage_doc.tutorial() # open the tutorial in a browser window browse_sage_doc.reference() browse_sage_doc.developer() browse_sage_doc.constructions()
and also
browse_sage_doc(identity_matrix)
opens up the docstring for identity_matrix
in a browser window. It doesn't look very pretty, but it's legible. You can also do
browse_sage_doc(identity_matrix, output='rst')
to output (as a string) the reST version of the docstring, and
browse_sage_doc(identity_matrix, view=False)
to output (as a string) the html version of the docstring.
New: following cremona's suggestion, this also adds the following top-level commands:
tutorial() reference() manual() # synonym for "reference" developer() constructions()
These open the corresponding document. The new command python_help
does what the old command help
did. The new command help does the following: with an argument, it acts like the old help -- that is, it calls python_help(arg)
. With no argument, it prints this message:
Welcome to Sage %s! To view the Sage tutorial in your web browser, type 'tutorial()', and to view the (very detailed) Sage reference manual, type 'manual()'. For help on any Sage function, for example 'matrix_plot', type 'matrix_plot?' to see a help message, type 'help(matrix_plot)' to see a very similar message, type 'browse_sage_doc(matrix_plot)' to view a message in a web browser, and type 'matrix_plot??' to look at the function's source code. To enter Python's interactive online help utility, type 'python_help()'. To get help on a Python function, module or package, type 'help(MODULE)' or 'python_help(MODULE)'.
(with the "%s" in the first line replaced by the version number).
Attachments (4)
Change History (27)
comment:1 Changed 13 years ago by
Description: | modified (diff) |
---|
comment:2 Changed 13 years ago by
comment:3 Changed 13 years ago by
On my Mac, I have the same problem with Sphinx 0.5.1, but not with Sphinx 0.6.2. On an ubuntu box, it works with both 0.5.1 and 0.6.2.
comment:4 follow-up: 5 Changed 13 years ago by
Keywords: | documentation added |
---|---|
Reviewers: | → mpatel, cremona |
I think this is a great facility. Just being able to pop up the 4 main docs so easily is worth including this!
When I tried browse_sage_doc(identity_matrix) and the like, I found that the first time I did it I got that error:
sage: browse_sage_doc(identity_matrix) --------------------------------------------------------------------------- IOError Traceback (most recent call last) /home/john/.sage/temp/ubuntu/12456/_home_john__sage_init_sage_0.py in <module>() /home/john/sage-4.1.1/local/lib/python2.6/site-packages/sage/misc/sagedoc.pyc in __call__(self, obj, output, view) 842 from sage.server.notebook.cell import Cell 843 cell = Cell(0, '0', '0', None) --> 844 cell.set_introspect_html(s) 845 html = cell._Cell__introspect_html 846 if view: /home/john/sage-4.1.1/local/lib/python2.6/site-packages/sage/server/notebook/cell.pyc in set_introspect_html(self, html, completing, verbose) 1587 finally: 1588 # Contents should be flushed on close(). -> 1589 fd_html = open(html_name, 'r') 1590 new_html = fd_html.read() 1591 fd_html.close() IOError: [Errno 2] No such file or directory: '/home/john/.sage/sage_notebook/doc/009e7e626d87d8b9c5ce659c5b01cdb7.html'
but the second time it worked fine. Same again with browse_sage_doc(EllipticCurve?).
I'm not sure how useful the output='rst' or the view=False options are though.
comment:5 Changed 13 years ago by
Replying to cremona:
I think this is a great facility. Just being able to pop up the 4 main docs so easily is worth including this!
When I tried browse_sage_doc(identity_matrix) and the like, I found that the first time I did it I got that error:
On some platforms, this seems to depend on using Sphinx 0.6.2 instead of the version installed with Sage, 0.5.1. Can you try the spkg at #6586 to see if that helps? (Use the one listed in the most recent comment.)
I'm not sure how useful the output='rst' or the view=False options are though.
Me neither, but this was in response to a discussion on sage-devel, in which the ability to see raw rst or raw html was viewed as potentially useful.
comment:6 follow-up: 7 Changed 13 years ago by
What if we moved the Sphinx-ify code to another or its own module? This might make it easier to develop and use in multiple contexts.
I'm willing to do this, though not immediately.
comment:7 follow-up: 10 Changed 13 years ago by
Replying to mpatel:
What if we moved the Sphinx-ify code to another or its own module? This might make it easier to develop and use in multiple contexts.
That sounds good. This ticket can be accepted as is (if people are happy with it), then the code can be reorganized later.
comment:8 Changed 13 years ago by
Summary: | [with patch, needs review] browse sage docs → [with patch, with positive review] browse sage docs |
---|
I tried this again after installing the new sphinx from #6586, and the problem I reported earlier has gone away.
So I'm giving this s positive review (noting that it should depend on #6586).
Just one thought -- new users might not think of typing "browse_sage_doc", so it might be helpful to include top-level commands tutorial(), manual() [for the reference manual], at least. Currently help() starts up the python help system which is not so useful in sage, and I would even suggest considering over-writing that with s basic sage help (which would probably just output a brief suggestion to try manual() or tutorial()).
comment:9 Changed 13 years ago by
(I re-attached the same patch so I could add the comment about it depending on #6586.)
comment:10 Changed 13 years ago by
Replying to jhpalmieri:
Replying to mpatel:
What if we moved the Sphinx-ify code to another or its own module? This might make it easier to develop and use in multiple contexts.
That sounds good. This ticket can be accepted as is (if people are happy with it), then the code can be reorganized later.
See #7000. I may wait until notebook separation is almost complete. Currently, Sphinx is a prerequisite for sagenb-0.1.8.tar.gz.
comment:11 Changed 13 years ago by
Status: | positive_review → needs_work |
---|
Here's a new patch. This uses "sphinxify" from sagenb, which is good.
Following cremona's suggestion above, it also adds top level commands: tutorial, manual, developer, constructions, each of which opens up the named document in a web browser. Furthermore, it redefines "help" so that it prints a short help message:
Welcome to Sage 4.2! To view the Sage tutorial in your web browser, type 'tutorial()', and to view the (very detailed) Sage reference manual, type 'manual()'. For help on any function, for example 'matrix_plot', type 'matrix_plot?' to see display a help message, type 'browse_sage_doc(matrix_plot)' to view the same message in a web browser, and type 'matrix_plot??' to look at the function's source code. To use Python's online help utility, type 'python_help()'.
As you can see from this message, the old function "help" is now called "python_help".
comment:12 Changed 13 years ago by
Status: | needs_work → needs_review |
---|
comment:13 Changed 13 years ago by
Summary: | [with patch, with positive review] browse sage docs → [with patch, needs review] browse sage docs |
---|
comment:14 Changed 13 years ago by
Description: | modified (diff) |
---|
Changed 13 years ago by
Attachment: | trac_6820-browsedocs-v3.patch added |
---|
Use Sphinx stylesheets and jsMath for docstrings. Apply only this patch.
comment:15 Changed 13 years ago by
Version 3:
- Uses Sphinx's stylesheet and jsMath to format individual docstrings nicely. Try
browse_sage_doc(identity_matrix)
. - May require upgrading jsMath to version 3.6c, because of Firefox's 3.5's same-origin policy for local files.
- Guesses the
obj
's name. See this, this, and/or this.
Problems:
- Math does not render properly because backslashes are stripped, somewhere.
- It may be better to use a HTML template instead of an inline triple-quoted string.
comment:16 Changed 13 years ago by
Okay, this patch doesn't accidentally strip the backslashes anymore. This depends on #6673, and indeed, it doesn't seem to work on Firefox.
Changed 13 years ago by
Attachment: | trac_6820-browsedocs-v4.patch added |
---|
depends on #6673. apply only this patch.
comment:17 Changed 13 years ago by
Thanks very much for restoring the backslashes --- I didn't think of EMBEDDED_MODE
. I'll try to take a closer look at the jsMath problem. If necessaary, there's #7322.
comment:18 Changed 13 years ago by
The patch at #7322 upgrades SageNB to jsMath 3.6c. Please be sure to run
sage -docbuild website html -j -S -aE
before checking that Firefox 3.5.x now typesets browse_sage_doc(Zmod)
.
comment:19 follow-up: 20 Changed 13 years ago by
Should we add a browse_sage_src()
for parity with the SageNB's ??
.
comment:20 Changed 13 years ago by
Authors: | John Palmieri → John Palmieri, Mitesh Patel |
---|---|
Reviewers: | mpatel, cremona → mpatel, cremona, jhpalmieri |
The patch at #7322 upgrades SageNB to jsMath 3.6c. Please be sure to run
sage -docbuild website html -j -S -aE
before checking that Firefox 3.5.x now typesets browse_sage_doc(Zmod).
It works! (At least on my Mac running OS X 10.5.)
Should we add a
browse_sage_src()
for parity with the SageNB's??
.
Not on this ticket.
I'm happy with this. I'm giving mpatel's contributions a positive review, so if someone can give my contributions a positive review, the patch can be merged.
comment:21 Changed 13 years ago by
Status: | needs_review → positive_review |
---|---|
Summary: | [with patch, needs review] browse sage docs → [with patch, positive review] browse sage docs |
comment:22 Changed 13 years ago by
Report Upstream: | → N/A |
---|---|
Summary: | [with patch, positive review] browse sage docs → Easy command-line access to HTML documentation and docstrings |
comment:23 Changed 13 years ago by
Merged in: | → sage-4.3.1.alpha0 |
---|---|
Resolution: | → fixed |
Reviewers: | mpatel, cremona, jhpalmieri → Mitesh Patel, John Cremona, John Palmieri |
Status: | positive_review → closed |
Sphinx 0.5.1 throws a strange exception in
Cell.set_introspect_html()
. I setverbose=True
and replacedsphinx_app.build(None, [rst_name])
withFollowing
sage -br
:The lock file remains in the doc cache directory. This may be peculiar to my current setup, but I can't investigate further right now.
Also, by default
set_introspect_html()
tries to delete the reST file.Should we delete leftover .lock files on startup?