Opened 8 years ago

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

trac_13064-search.patch (2.5 KB) - added by jhpalmieri 7 years ago.
trac_13064-finite_rings_doc-ts.patch (114.1 KB) - added by tscrim 7 years ago.

Download all attachments as: .zip

Change History (19)

comment:1 Changed 8 years ago by nbruin

I don't think the problem is that it cannot search in methods. For instance, if you try

frobenius

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 that sage.rings.finite_rings.element_givaro.FiniteField_givaroElement is simply not included there.

Last edited 8 years ago by nbruin (previous) (diff)

comment:2 Changed 8 years ago by ppurka

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 7 years ago by tscrim

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 7 years ago by ppurka

Sure, go ahead.

comment:5 Changed 7 years ago by tscrim

  • Authors set to Travis Scrimshaw
  • 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: Changed 7 years ago by jhpalmieri

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 7 years ago by ppurka

Replying to jhpalmieri:

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?

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: Changed 7 years ago by tscrim

Replying to jhpalmieri:

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?

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 7 years ago by ppurka

Replying to tscrim:

Also search_def according to its documentation is the same as search_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 7 years ago by jhpalmieri

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

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  
    3131    function will automatically search for all of the words. Pages
    3232    containing fewer words won't appear in the result list.{% endtrans %}
    3333  </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>
    3440  <form action="" method="get">
    3541    <input type="text" name="q" value="" />
    3642    <input type="submit" value="{{ _('search') }}" />

Changed 7 years ago by jhpalmieri

Changed 7 years ago by tscrim

comment:12 Changed 7 years ago by tscrim

  • Dependencies set to #13180

I've rebased over #13180. I'm happy with the change to the search page.

comment:13 Changed 7 years ago by tscrim

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 7 years ago by tscrim

  • Cc sage-combinat added

comment:15 Changed 7 years ago by ppurka

  • Authors changed from Travis Scrimshaw to John Palmieri, Travis Scrimshaw
  • 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 7 years ago by tscrim

  • Reviewers changed from Travis Scrimshaw, Punarbasu Purkayastha to Punarbasu Purkayastha

Thank you for doing the final review on this.

Best,
Travis

comment:17 Changed 7 years ago by jdemeyer

  • Merged in set to sage-5.7.beta4
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.