# Docstring docs and html docs are different

If I try to type for example factor? in sage console It yields very detailed output with documentation based on dosctrings. But if I try to find factor in html\pdf docs (offline and online) there is no such search results.

So two questions:

• How to get that complete docsrting help from outside sage console?
• Why they are different?

P.S. Example factor? output:

Signature: factor(n, proof=None, int_=False, algorithm='pari', verbose=0, **kwds)

Docstring: Returns the factorization of "n". The result depends on the type of "n".

If "n" is an integer, returns the factorization as an object of type "Factorization".

If n is not an integer, "n.factor(proof=proof, **kwds)" gets
called. See "n.factor??" for more documentation in this case.

Warning: This means that applying "factor" to an integer result of a symbolic computation will not factor the integer, because it is considered as an element of a larger symbolic ring.EXAMPLES:

    sage: f(n)=n^2
sage: is_prime(f(3))
False
sage: factor(f(3))
9 ...

edit retag close merge delete

Sort by » oldest newest most voted

Hello! There are various methods you can use to find that documentation in the online HTML manual.

1. Go to the Sage Reference Manual. Under the "General Information" section you will find the option "Index". When you click on that, a page will be open with the alphabet. In your case, you have to press "F", of course, and then search for "factor()". Click on in, and you will have the same information as with factor?.
2. If you use the factor? (or factor??) command on your REPL, you will notice at the end of the printed text a part that says

File: /Scientific/SageMath/local/lib/python2.7/site-packages/sage/arith/misc.py

This tells you that the factor() function is located at the module "sage.arith.misc". So go to the Sage Reference Manual, go to the "General information" section at the end of the page, and select "Module Index". A page showing every single Python module defined by Sage will appear in alphabetical oreder. Under the "A" (for "arith") you will find the entry for "sage.arith.misc". Click on it, and you will be shown all the subroutines defined in that file, including the factor() function.

3. You can use a combination of both previous methods: Use the factor?? command, where you will see the line I mentioned in point 2. Then you go to the Sage Reference Manual, click on "Index", and introduce the module name, "sage.arith.misc". You click on the name of the module when the search results appear. There you'll find the "factor()" info.

4. Finally, you can write search_doc('sage.arith.misc.factor', whole_word=True), which, of course, is based on the result of factor?, as in point 2. That will search the whole documentation for the words "sage.arith.misc.factor". Of the entire output of this command, you are interested in the line that contains id="sage.arith.misc.factor":

en/reference/rings_standard/sage/arith/misc.html:1461:<dt id="sage.arith.misc.factor">

Notice the part "en/reference/rings_standard/sage/arith/misc.html"? If you prepend the Reference Manual address to that ("https://doc.sagemath.org/html/en/reference/rings_standard/sage/arith/misc.html"), you will find the documentation you're looking for.

Since the PDF documentation is based on the HTML version, it should not be difficult to adapt this methods to find the PDF documentation for factor() or any other function or method.

I hope this helps!

more

This function is here in the reference manual. This is one of the many listings when you search for "factor" in the reference manual, but it's nowhere near the first one. You can find it by looking at the end of the output for factor?: it says "File: .../site-packages/sage/arith/misc.py", and then you can search the listings for "arith.misc".

more

factor?? or factor.__doc__, is this the answer to the question?!

To make the answer longer, here are the first few lines of the doc string:

sage: print '\n'.join(factor.__doc__.split('\n')[:20])

Returns the factorization of n.  The result depends on the
type of n.

If n is an integer, returns the factorization as an object
of type Factorization.

If n is not an integer, n.factor(proof=proof, **kwds) gets called.
See n.factor?? for more documentation in this case.

.. warning::

This means that applying factor to an integer result of
a symbolic computation will not factor the integer, because it is
considered as an element of a larger symbolic ring.

EXAMPLES::

sage: f(n)=n^2
sage: is_prime(f(3))
sage:

more