Write API documentation for AMRClaw

[xinshengqin]

The Docathon suggested 4 different types of documentation for a project:

• tutorial
• user documentation
• API documentation
• examples and galleries

What we already have for clawpack are more in the range of tutorial, user documentation and galleries. The API documentation is more targeted at developers of the code.

I think source code of AMRCLAW is more like a lower level part of Clawpack, which is more likely to be read by developers. So probably I should add an API documentation category for AMRCLAW and try to make something like this for each subroutine:

Type: function
String Form:<function svd at 0x7f351c2cab90>
File: /home/shawn/.local/lib/python2.7/site-packages/numpy/linalg/linalg.py
Definition: np.linalg.svd(a, full_matrices=1, compute_uv=1)
Docstring:
Singular Value Decomposition.

Factors the matrix a as u * np.diag(s) * v, where u and v
are unitary and s is a 1-d array of a's singular values.

Parameters

a : (..., M, N) array_like
A real or complex matrix of shape (M, N) .
full_matrices : bool, optional
If True (default), u and v have the shapes (M, M) and
(N, N), respectively. Otherwise, the shapes are (M, K)
and (K, N), respectively, where K = min(M, N).
compute_uv : bool, optional
Whether or not to compute u and v in addition to s. True
by default.

Returns

u : { (..., M, M), (..., M, K) } array
Unitary matrices. The actual shape depends on the value of
full_matrices. Only returned when compute_uv is True.
s : (..., K) array
The singular values for every matrix, sorted in descending order.
v : { (..., N, N), (..., K, N) } array
Unitary matrices. The actual shape depends on the value of

Examples

a = np.random.randn(9, 6) + 1j*np.random.randn(9, 6)

[xinshengqin]

By doing this, I can keep adding API documentations for AMRCLAW as I go through its code.

[ketch]

@xinshengqin I retitled this to more accurately reflect what you seem to intend.

[xinshengqin]

@ketch Thanks! That's exactly what I mean.

[rjleveque]

@xinshengqin: I dug up the old amrclaw docs that I mentioned the other day. There's a rendered version at http://depts.washington.edu/clawpack/amrclaw_docs/amrclaw/

A former students started this years ago from Version 4.6 and it never got finished off and has not been updated for later versions.

I just added the .rst files to a branch rjleveque/amrclaw_docs_4.6 on my fork in case they are useful to you.

[xinshengqin]

@rjleveque Thanks! I just have a look at them and they definitely help.

[rjleveque]

#157 is a good start.