The documentation should search methods in classes

[ppurka]

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

Depends on #13180

CC: @sagetrac-sage-combinat

Component: documentation

Author: John Palmieri, Travis Scrimshaw

Reviewer: Punarbasu Purkayastha

Merged: sage-5.7.beta4

Issue created by migration from https://trac.sagemath.org/ticket/13064

[nbruin]

comment:1

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.

[ppurka]

comment:2

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.

[tscrim]

comment:3

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?

[ppurka]

comment:4

Sure, go ahead.

[tscrim]

comment:5

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.

[tscrim]

Author: Travis Scrimshaw

[jhpalmieri]

comment:6

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?

[ppurka]

comment:7

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?

[tscrim]

comment:8

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.

[ppurka]

comment:9

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.

[jhpalmieri]

comment:10

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.

[jhpalmieri]

comment:11

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:

--- local/lib/python/site-packages/Sphinx-1.1.2-py2.7.egg/sphinx/themes/basic/search.html	2012-11-17 10:34:58.000000000 -0800
+++ devel/sage/doc/common/themes/sage/search.html	2012-11-17 22:11:12.000000000 -0800
@@ -31,6 +31,12 @@
     function will automatically search for all of the words. Pages
     containing fewer words won't appear in the result list.{% endtrans %}
   </p>
+  <p>
+    {% trans %}Note also that you can also call "search_src(...)"
+    while running Sage to search Sage's source code. You can also
+    browse Sage's source code by calling "hg_sage.serve()" while running
+    Sage.{% endtrans %}
+  </p>
   <form action="" method="get">
     <input type="text" name="q" value="" />
     <input type="submit" value="{{ _('search') }}" />

[jhpalmieri]

Attachment: trac_13064-search.patch.gz

[tscrim]

comment:12

Attachment: trac_13064-finite_rings_doc-ts.patch.gz

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

[tscrim]

Dependencies: #13180

[tscrim]

comment:13

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

[ppurka]

Changed author from Travis Scrimshaw to John Palmieri, Travis Scrimshaw

[ppurka]

comment:15

Sorry for sitting on this for so long. I have nothing else to add to this.

[ppurka]

Reviewer: Travis Scrimshaw, Punarbasu Purkayastha

[tscrim]

comment:16

Thank you for doing the final review on this.

Best,

Travis

[tscrim]

Changed reviewer from Travis Scrimshaw, Punarbasu Purkayastha to Punarbasu Purkayastha

[jdemeyer]

Merged: sage-5.7.beta4