Docstring docs and html docs are different

asked 2019-07-31 00:00:31 +0200

petRUShka
301 ●10 ●23 ●30

updated 2019-07-31 00:01:06 +0200

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 flag offensive close merge delete

add a comment

3 Answers

Sort by » oldest newest most voted

answered 2019-07-31 08:35:29 +0200

dsejas
2819 ●14 ●49 ●95

updated 2019-07-31 22:14:52 +0200

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

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?.
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.
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.
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!

edit flag offensive delete link

add a comment

answered 2019-07-31 03:40:59 +0200

dan_fulea
5337 ●5 ●43 ●90

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:

edit flag offensive delete link

add a comment

answered 2019-07-31 06:05:18 +0200

John Palmieri

8551 ●19 ●71 ●186 http://www.math.washin...

updated 2019-07-31 07:09:06 +0200

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".

edit flag offensive delete link

add a comment

Your Answer

Please start posting anonymously - your entry will be published after you log in or create a new account.

Add Answer

Docstring docs and html docs are different

3 Answers

Your Answer

Question Tools

Stats

Related questions

Docstring docs and html docs are different edit

3 Answers

Your Answer

Question Tools

Stats

Related questions

Docstring docs and html docs are different