Ask Your Question
0

Docstring docs and html docs are different

asked 2019-07-30 17:00:31 -0600

petRUShka gravatar image

updated 2019-07-30 17:01:06 -0600

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

3 answers

Sort by ยป oldest newest most voted
3

answered 2019-07-31 01:35:29 -0600

dsejas gravatar image

updated 2019-07-31 15:14:52 -0600

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!

edit flag offensive delete link more
2

answered 2019-07-30 23:05:18 -0600

updated 2019-07-31 00:09:06 -0600

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 more
0

answered 2019-07-30 20:40:59 -0600

dan_fulea gravatar image

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 more

Your Answer

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

Add Answer

Question Tools

1 follower

Stats

Asked: 2019-07-30 17:00:31 -0600

Seen: 55 times

Last updated: Jul 31