- make rst.Writer support substitution_definitions with multi-character
  strings with embedded unicode characters.

- consider moving directly from rST to PDF instead of generating HTML
  as a middle-step...
  ==> perhaps make that an option.

- tree hierarchy: when rendering non-"/" tree, it should start at that
  point, not from "/". eg. `pdescribe config.ini -T /path/to/foo` should
  result in:

    /path/to/foo/
    |-- sub-controller/
    |-- ...
    `-- ...

  instead of:

    /
    `-- path/
        `-- to/
            `-- foo/
                |-- sub-controller/
                |-- ...
                `-- ...

- force 'format' to lower case?... prolly - but where?

- make `DescriberController.formattext_html` try to load docutils, and
  if successful, do rST formatting with that. otherwise fallback to the
  pseudo-stuff...

- update DescribeController to inspect decorator `method` parameters

- should per-stanza configurations default to global configuration
  defaults? yes. but that is fairly involved.

- add an option to 'force-create' controllers that are referenced by
  class instead of by instance?

- remove the inconsistency between filters receiving `data`
  vs. `options`...

- rename `data`, `context`, `proc` ==> `stage` (it's the best i could
  come up with)

- when a numpydoc section is :doc.copy:'d, the referenced sections
  show up *before* any locally defined sections... oops. eg:

     class Controller:
       def get():
         ':Returns: ...'
       def put():
         info... :Parameters: ... :doc.copy:`GET:.:Returns`

  ==> put's documentation will be:
    info...
    Returns...
    Paramaters...

  fix that so that order is always 'summary => params => returns =>
  raises'

- resolve how :doc.*: linking works between endpoints that have/don't
  have declared methods (i.e. Controller vs. RestController).

- perhaps move the default rST generation to use
    render.template = pyramid_describe:template/render.mako
  from that template:
    This template is currently not being used. It was just a thought
    on how default rST rendering could be converted to use mako
    templating... (and thus simpler to create a new template since
    there would be an example that "uses all features"...)

- rearchitect... we need to move to the following steps/pipeline:
    # globally cacheable:
      1. assemble: collects all endpoints to be documented
      2. parse: parse all documentation into formal syntax
    # per-request handling:
      3. filter: restrict which endpoints are visible/massage documentation
      4. render: render endpoints into one rST document
      5. format: format the rST document into target format
