Opened 10 years ago
Closed 9 years ago
#13064 closed defect (fixed)
The documentation should search methods in classes
Reported by: | ppurka | Owned by: | mvngu |
---|---|---|---|
Priority: | major | Milestone: | sage-5.7 |
Component: | documentation | Keywords: | documentation |
Cc: | sage-combinat | Merged in: | sage-5.7.beta4 |
Authors: | John Palmieri, Travis Scrimshaw | Reviewers: | Punarbasu Purkayastha |
Report Upstream: | N/A | Work issues: | |
Branch: | Commit: | ||
Dependencies: | #13180 | Stopgaps: |
Description
The documentation here http://www.sagemath.org/doc/reference/search.html should be able to search methods (those not starting with _
) in the classes. For instance, the following search http://www.sagemath.org/doc/reference/search.html?q=integer_representation gives zero results even though integer_representation
is a valid method for an element of GF(2^p)
.
sage: F = GF(2**3, 'a') sage: b = F.random_element(); b a^2 + a sage: b.integer_representation() 6
Attachments (2)
Change History (19)
comment:1 Changed 10 years ago by
comment:2 Changed 10 years ago by
My guess was that maybe it only searches and indexes methods which are present in global scope. I will have to look more carefully to see why it is missing some of the methods.
comment:3 Changed 10 years ago by
The problem (in this particular case) is that the documentation for these finite fields are not included/built because there's no references in a .rst
file. Would anyone mind if I reuse this ticket to update the appropriate .rst
file?
comment:4 Changed 10 years ago by
Sure, go ahead.
comment:5 Changed 10 years ago by
- Status changed from new to needs_review
I've added a finite field .rst
file (there might be others that are missing out there...) and cleaned up the documentation for those files so the docbuild won't complain. Please review.
comment:6 follow-ups: ↓ 7 ↓ 8 Changed 10 years ago by
I think that for the usage in the ticket description, the functions search_src
and search_def
are much more appropriate than searching the documentation, which only searches the documentation: the reference manual, the tutorial, etc. Maybe search_src
etc. should be better publicized. There should be a good way to put a note about them on the search page for the docs, for instance. Would that be a good idea?
comment:7 in reply to: ↑ 6 Changed 10 years ago by
Replying to jhpalmieri:
I think that for the usage in the ticket description, the functions
search_src
andsearch_def
are much more appropriate than searching the documentation, which only searches the documentation: the reference manual, the tutorial, etc. Maybesearch_src
etc. should be better publicized. There should be a good way to put a note about them on the search page for the docs, for instance. Would that be a good idea?
Definitely a good idea. I wasn't aware of this search_src
function until very recently. search_def
seems new to me :) Why doesn't the documentation searching function have these two integrated in them? Maybe a link from the documentation search page?
comment:8 in reply to: ↑ 6 ; follow-up: ↓ 9 Changed 10 years ago by
Replying to jhpalmieri:
I think that for the usage in the ticket description, the functions
search_src
andsearch_def
are much more appropriate than searching the documentation, which only searches the documentation: the reference manual, the tutorial, etc. Maybesearch_src
etc. should be better publicized. There should be a good way to put a note about them on the search page for the docs, for instance. Would that be a good idea?
Almost certainly. Something like: "In sage, you can use search_src
[with a link to its doc] to find functions in all of the source code, including private functions (those that begin with a leading underscore '_
')." Possibly also adding: "If there is a module not linked in this documentation, it is a bug that needs to be reported."
Also search_def
according to its documentation is the same as search_src
.
comment:9 in reply to: ↑ 8 Changed 10 years ago by
Replying to tscrim:
Also
search_def
according to its documentation is the same assearch_src
.
Actually they are different functions. Their input and output formats are similar. The search_def
searches only function names while the search_src
searches through the whole source code, matching any line with the search string.
comment:10 Changed 10 years ago by
Those search_*
functions are only available when you're running Sage, while the documentation search page just needs the build documentation — no need for Sage to be running. So that's one reason why they're not integrated, and probably why they shouldn't be.
I'm imagining text like "You can also run search_src(...)
from while running Sage to search the source code. You can also browse the source code by running hg_sage.serve()
from Sage."
Re search_def('blah')
: it is like search_src('blah')
, but it restricts its search to lines of the form def blah
or cdef blah
, so it sees both functions and methods which contain 'blah' in their name.
comment:11 Changed 10 years ago by
Here's a sample patch. This changes Sage so it uses its own "search.html" page instead of the default one. The difference between the default one and the one in the patch is this:
-
search.html
old new 31 31 function will automatically search for all of the words. Pages 32 32 containing fewer words won't appear in the result list.{% endtrans %} 33 33 </p> 34 <p> 35 {% trans %}Note also that you can also call "search_src(...)" 36 while running Sage to search Sage's source code. You can also 37 browse Sage's source code by calling "hg_sage.serve()" while running 38 Sage.{% endtrans %} 39 </p> 34 40 <form action="" method="get"> 35 41 <input type="text" name="q" value="" /> 36 42 <input type="submit" value="{{ _('search') }}" />
Changed 10 years ago by
Changed 10 years ago by
comment:12 Changed 10 years ago by
- Dependencies set to #13180
I've rebased over #13180. I'm happy with the change to the search page.
comment:13 Changed 10 years ago by
This applies cleanly for me on 5.5.rc0, so let's try again.
For patchbot:
Apply: trac_13064-finite_rings_doc-ts.patch, trac_13064-search.patch
comment:14 Changed 9 years ago by
- Cc sage-combinat added
comment:15 Changed 9 years ago by
- Reviewers set to Travis Scrimshaw, Punarbasu Purkayastha
- Status changed from needs_review to positive_review
Sorry for sitting on this for so long. I have nothing else to add to this.
comment:16 Changed 9 years ago by
- Reviewers changed from Travis Scrimshaw, Punarbasu Purkayastha to Punarbasu Purkayastha
Thank you for doing the final review on this.
Best,
Travis
comment:17 Changed 9 years ago by
- Merged in set to sage-5.7.beta4
- Resolution set to fixed
- Status changed from positive_review to closed
I don't think the problem is that it cannot search in methods. For instance, if you try
you'll see plenty of methods show up. Are you positive that
integer_representation
is documented in the "sage reference"? If you look in the index under "I", you'll see many methods indexed, but not that one. So I guess thatsage.rings.finite_rings.element_givaro.FiniteField_givaroElement
is simply not included there.