Reading Python documentation

What do docs typically look like?

Why do they always look like that?

So knowledge you gain from one package often transfers to another

(And it can be useful to know how to write them too - see next session)

Numpy's Documentation

https://docs.scipy.org/doc/numpy/

  1. Distinguishes between "user guide" (https://docs.scipy.org/doc/numpy/user/index.html), which is meant to be read ("narrative" docs)
  2. There's also a contributor guide (but we won't dwell on that)
  3. And "reference" (https://docs.scipy.org/doc/numpy/reference/index.html) - often just a list of functions (e.g. https://docs.scipy.org/doc/numpy/reference/routines.array-creation.html)
  4. This is common where there's a straightforward single thing to work with (e.g., numpy arrays)

Lets look at numpy.empty and try to understand how to use it.

Astropy's Docs

(and many affiliated packages)

  1. If it's not the main web site, you can usually find it there: http://www.astropy.org
  2. But be sure you're on the stable version's docs (http://docs.astropy.org/), but not the developer docs (http://devdocs.astropy.org/), or some other version (see the upper-left)
  3. Divided up by topic: units, coordinates, etc.
  4. Within these, there's a difference between narrative docs (e.g. http://docs.astropy.org/en/stable/coordinates/skycoord.html) and API (e.g. http://docs.astropy.org/en/stable/coordinates/index.html#reference-api).
  5. The API includes both functions and classes. Sometimes it is the only place something important is listed!
  6. There's a "developer" guide that is offset from the user docs, but still a part of it because sometimes it's useful.

Lets look at astropy.coordinates.SkyCoord and see what a more complex class looks like. (Particularly that *args, **kwargs business!) - can get there from the live links in the skycoord narrative docs mentioned above.

Sphinx itself

  1. The main site is the docs: http://www.sphinx-doc.org/
  2. There's a quick start (http://www.sphinx-doc.org/en/1.4.8/tutorial.html), and "Contents" (http://www.sphinx-doc.org/en/1.4.8/contents.html), but no clearly distinct API

Stack Overflow

http://stackoverflow.com/questions/tagged/python