Documentation format

[Georg Muntingh]

I noticed that the documentation format doesn't contain a 'see
also-section'. When using a CAS I always think such sections to be very
useful, because it often provides a convenient method for finding the
function I'm looking for.

Maybe there is a good reason that they are not there, but at the moment
I can't really think of one. There might be some scalability-issues
when new functions are added, but it should not be very difficult to
find possible candidates once a couple of links have been provided. A
small program could just follow the links you already provided to a
certain depth, and then suggest the links that turn up several times.
This is in the spirit of the automatic testing of the documentation.

[Nick Alexander]

Hi Georg,

This is only somewhat on topic. I've been rewriting the scripts that
generate the reference, and my understanding is that there is no
'documentation format'; there are a series of loosely followed
conventions.

My changes will typeset any UPCASE: heading in a somewhat sensible
manner, doing its best to honour existing conventions such as EXAMPLES:
and AUTHORS:. If you think an ALSO: section would be useful, such a
thing could be arranged. At some point, I would like to hyperlink the
inline documentation, sage tracebacks, notebook, etc, so an ALSO:
section would fit right in.

If other people have wishes for SAGE documentation, please let me know.
No guarantees, but I'll do what I can.

Cheers,
Nick

[Iftikhar Burhanuddin]

On Mon, 18 Dec 2006, Nick Alexander wrote:
> and AUTHORS:. If you think an ALSO: section would be useful, such a
> thing could be arranged. At some point, I would like to hyperlink the
> inline documentation, sage tracebacks, notebook, etc, so an ALSO:
> section would fit right in.

Hi,

I put in a NOTES section in the SAGE Programming Guide which was released
as part of sage-1.5

I suggest developers keep track of (updates to) coding conventions, etc.
by revisiting appropriate documentation which come with milestone-version
releases of SAGE.

Regards,
Ifti.
====
http://modular.math.washington.edu/sage/doc/html/prog/node4.html
Every function should have a docstring that includes the following
information:

* A one-sentence description of the function, followed by a blank line.

* An INPUT and an OUTPUT block for input and output arguments (see below
for format). The type names should be descriptive, but do not have to
represent the exact SAGE/Python types. For example, use ``integer'' for
anything that behaves like an integer; you do not have to put a precise
type name such as int.
* An EXAMPLES block for examples. This is not optional.
* A NOTES block for special notes (optional).
* An AUTHORS block (important!).

[Iftikhar Burhanuddin]

On Mon, 18 Dec 2006, Iftikhar Burhanuddin wrote:
>
> I put in a NOTES section in the SAGE Programming Guide which was released
> as part of sage-1.5

Correction. The docstring NOTES section existed in the programming guide
prior to my editing. I merely incorporated it into the docstring template.

Regards,
Ifti
========
http://modular.math.washington.edu/sage/doc/html/prog/node4.html

Every function should have a docstring that includes the following
information:

* A one-sentence description of the function, followed by a blank
line.
* An INPUT and an OUTPUT block for input and output arguments (see
below for format). The type names should be descriptive, but do not have
to represent the exact SAGE/Python types. For example, use ``integer'' for
anything that behaves like an integer; you do not have to put a precise
type name such as int.
* An EXAMPLES block for examples. This is not optional.
* A NOTES block for special notes (optional).
* An AUTHORS block (important!).

Use the following template when documenting functions. Note the
indentation:

def point(self, x=1, y=2):
r""" # note the r for "raw string"
This function returns the point $(x^5,y)$.

INPUT:
self -- anything special about self
x -- integer (default: 1) the ...
y -- integer (default: 2) the ...

OUTPUT:
integer -- the ...

EXAMPLES:
This example illustrates ...
sage: A = ModuliSpace()
sage: A.point(2,3)
xxx

We now ...
sage: B = A.point(5,6)
sage: xxx

It is an error to ...
sage: C = A.point('x',7)
Traceback (most recent call last):
...
TypeError: unable to convert x (=r) to an integer

NOTES:
...

AUTHORS:
- William Stein (2005-01-03)
- First_name Last_name (yyyy-mm-dd)
"""
<body of the function>