Additional documentation features / overhaul

[pmolodo]

From elron...@gmail.com on January 06, 2011 11:34:19

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: http://code.google.com/p/pymel/issues/detail?id=226

[pmolodo]

From elron...@gmail.com on January 27, 2011 11:29:19

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.

[pmolodo]

From elron...@gmail.com on June 21, 2012 17:07:59

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)