Doc string parameter documentation

[Jim Baker]

On 08/22/2011 06:00 PM, Gustavo Niemeyer wrote:
>> We've seem to grown a few different incompatible ways of documenting parameters
>> in code. Originally we were using twisted's pydoctor syntax, but we since
>> migrated to using sphinx for documentation.
>>
>> We should use one style consistently. Given our usage of sphinx, I think all
>> parameter documentation references should be cleaned up to use its style as we
>> go.
> I'm personally happy with any format as long as we're consistent.
> Given our use of Sphinx, your proposal sounds good too.  +1!
>
The parameter list support is very nice. Fortunately it's very close to
what old pydoctor and more recently our semistandard ;) RST listing of
parameters is, so conversion will be trivial.

The other thing to note here is that we can continue to use the
default-domain of py. Some markup already is doing this, eg, the use of
:method:`actual_method_name`, vs having to do this a bit more
redundantly everywhere as :py:method:`actual_method_name`.

In the JFDI model, we should just starting using Sphinx to generate docs
from docstrings. Wrongly formatted docstrings will still be visible and
useful, just ugly and lacking conveniences like cross-referencing.

- Jim


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 554 bytes
Desc: OpenPGP digital signature
URL: <https://lists.ubuntu.com/archives/juju/attachments/20110823/ca49feea/attachment-0002.pgp>