#320 Docstrings Sectins in Outliner

[Chad Dombrova]

reStructuredText is the basis for many python documentation generators ( epydoc and sphinx to name two ). documentation placed within python docstrings can often become very lengthy with many topics and sub-topics. it would be useful to have the docstrings and their headings in the pydev outliner for quickly jumping between headings while writing documentation. the docstring headings would be represented like other objects in the outliner: as a tree structure with arrow drop-downs. docstrings without headings would not appear in the outliner.

the specifications for reStructuredText headings can be found here:
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections

## ---- start file ----------

"""
*******************************
Pymel
*******************************

Description.....

=======================================
What's New in Version 0.8
=======================================
---------------------------------------
Licensing Change
---------------------------------------
pymel is now offered under the New BSD license.

---------------------------------------
Non-Backward Compatible Changes
---------------------------------------
- Changed and Renamed Functions:
- Attribute disconnection operator has changed from <> to //
- Node classes no longer inherit from unicode: see `PyNodes Are Not Strings`_
- Instantiation of non-existent PyNode objects now results in an exception: see `Non-Existent Objects`_
- _BaseObj has been replaced with `PyNode` class

---------------------------------------
Other Additions and Changes
---------------------------------------

- New Classes:
- The `MelGlobals` class adds dictionary-like access to mel global variables
- The `Version` class simplifies cross platform comparison of versions of maya

=======================================
Installation
=======================================

---------------------------------------
Pymel Package
---------------------------------------

If on linux or osx, the simplest way to install pymel is to place the unzipped pymel folder in your scripts directory
"""

class Foo(object):
"""
===============
Main Heading
===============

Section 1
---------
some stuff goes here

Section 2
---------
some more stuff goes here
"""

def __init__(self):
"""
these docstrings have no headings and won't show up in the outliner
"""
pass

## ---- end file ----------

The outliner view would appear as below:

-----------------------------------------------------
KEY:
* docstring
@ class
$ function

-----------------------------------------------------
(*) docs
(*) Pymel
(*) What's New in Version 0.8
(*) Licensing Change
(*) Non-Backward Compatible Changes
(*) Installation
(*) Pymel Package

(@) Foo
(*) docs
(*) Main Heading
(*) Section 1
(*) Section 2
($) __init__

-----------------------------------------------------

[Chad Dombrova]

the sample file

[Chad Dombrova]

looks like my tabs were all stripped. here's what the outliner would appear:

KEY:
* docstring
@ class
$ function

-----------------------------------------------------
(*) docs
--(*) Pymel
----(*) What's New in Version 0.8
------(*) Licensing Change
------(*) Non-Backward Compatible Changes
----(*) Installation
------(*) Pymel Package

(@) Foo
--(*) docs
----(*) Main Heading
------(*) Section 1
------(*) Section 2
--($) __init__