Additional documentation features / overhaul

[GoogleCodeExporter]

Docs desperately need some additional features / updates / fixes:

- Way to show all / inherited methods for a given class (ie, when showing docs 
for a Joint, also see the methods for a Transform)

- See / link to child classes

These first items should ideally be part of an auto-generated doc system - so 
look into extending / switching doc generation system (epydoc? doxygen? extend 
sphinx more?)

Links to the official maya docs that a given method / class in inherits from 
(both api docs and cmd docs)

Cleanup of auto-generated docs (see, ie, docs for DependNode.addAttr)

- More standardization of docs; look into switching over to NumPy/SciPy 
standard - see:
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
...also make sure all external docs conform to standard

Original issue reported on code.google.com by elron...@gmail.com on 6 Jan 2011 at 7:34

[GoogleCodeExporter]

As far as standardizing of docs - currently, our code has a number of different 
conventions:

:Parameters:
    argname : argtype
       This arg controls this stuff
:rtype: str

:Parameters:
argname : argtype
    This arg controls this stuff
:rtype: str

:param argname: This arg controls this stuff
:type argname: argtype
:rtype: str

...additionally, the argument types (ie, int) are sometimes enclosed in 
backticks - `int` - and sometimes not.

However, I propose using none of these, but using on the numpy / scipy 
documentation standard, as it is a good mix of readability / pretty output... 
and, it already has a very clear documentation guideline.

https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

Parameters
----------
argname : argtype
   This arg controls this stuff

Returns
-------
out : str
    Description of return value

(... or, possibly, using the numpy format, but the :rtype: for return values 
where we don't need a description, since this is significantly more compact?)

Would need to convert over existing code, and auto-generated docstrings (from 
parsing maya docs) to use this standard.

Original comment by elron...@gmail.com on 27 Jan 2011 at 7:29

[GoogleCodeExporter]

Also, add in ability to add "modifiers" to wrapped docstrings - ie, for ls 
command, a way to tell it to replace the string "The ls command returns the 
names (and optionally the type names) of objects in the scene" with "The ls 
command returns PyNode objects (or optionally type names) for nodes in the 
scene".
Also, add in ability to issue a warning if a string is not found... (to deal 
with changes in docstrings)

Original comment by elron...@gmail.com on 22 Jun 2012 at 12:07