Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

The documentation should search methods in classes #13064

Closed
ppurka opened this issue May 30, 2012 · 22 comments
Closed

The documentation should search methods in classes #13064

ppurka opened this issue May 30, 2012 · 22 comments

Comments

@ppurka
Copy link
Member

ppurka commented May 30, 2012

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
Copy link
Contributor

nbruin commented May 30, 2012

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
Copy link
Member Author

ppurka commented May 30, 2012

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
Copy link
Collaborator

tscrim commented Nov 17, 2012

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
Copy link
Member Author

ppurka commented Nov 17, 2012

comment:4

Sure, go ahead.

@tscrim
Copy link
Collaborator

tscrim commented Nov 18, 2012

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
Copy link
Collaborator

tscrim commented Nov 18, 2012

Author: Travis Scrimshaw

@jhpalmieri
Copy link
Member

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
Copy link
Member Author

ppurka commented Nov 18, 2012

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
Copy link
Collaborator

tscrim commented Nov 18, 2012

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
Copy link
Member Author

ppurka commented Nov 18, 2012

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
Copy link
Member

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
Copy link
Member

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
Copy link
Member

Attachment: trac_13064-search.patch.gz

@tscrim
Copy link
Collaborator

tscrim commented Nov 20, 2012

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
Copy link
Collaborator

tscrim commented Nov 20, 2012

Dependencies: #13180

@tscrim
Copy link
Collaborator

tscrim commented Nov 26, 2012

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
Copy link
Member Author

ppurka commented Feb 7, 2013

Changed author from Travis Scrimshaw to John Palmieri, Travis Scrimshaw

@ppurka
Copy link
Member Author

ppurka commented Feb 7, 2013

comment:15

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

@ppurka
Copy link
Member Author

ppurka commented Feb 7, 2013

Reviewer: Travis Scrimshaw, Punarbasu Purkayastha

@tscrim
Copy link
Collaborator

tscrim commented Feb 7, 2013

comment:16

Thank you for doing the final review on this.

Best,

Travis

@tscrim
Copy link
Collaborator

tscrim commented Feb 7, 2013

Changed reviewer from Travis Scrimshaw, Punarbasu Purkayastha to Punarbasu Purkayastha

@jdemeyer
Copy link

jdemeyer commented Feb 9, 2013

Merged: sage-5.7.beta4

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

5 participants