- typereg renames:
  - type to datatype
  - datatype "params" to "qualifiers"

- for non-REST controllers, extract method from @expose decorator...
  ==> what about non-pyramid_controllers?

- implement controller-to-method access inheritance, ie:

    class Controller(RestController):
      '@PUBLIC'
      @expose
      def get(): pass
      @expose
      def delete():
        '@INTERNAL'
        pass

    ==> the `GET` method should be public, but the `DELETE`
        method should be internal

    ==> what about inheritance to non-REST methods?

- test that mixing of channel type defs and docs works, eg:

    Returns
    -------

    some text.

    HTTPForbidden
      not allowed

    HTTPBadRequest
      bad data

  ==> this gets *parsed* correctly, but does it get reassembled
      correctly during doctree generation??? check!

- the type registry needs to be revamped... some issues:
  - rename "scalar" to "primitive"
  - have immutable primitive singletons
  - manage unknown types better...
  - do dereferencing better...
  - get rid of "auto" types... and move to reference counting?
    or some other (better!) strategy for only rendering types
    that are referenced...

- handle case where an anonymous dict param/return/raise has no
  keys after filtration. eg. an endpoint takes a single parameter,
  "all", but that is marked internal. thus public users won't see
  the parameter, but a "dict" still will be taken as input...

- use pygments to syntax-highlight code blocks!

- when merging two docorated types that have local documentation, the
  location of the docorators is a bit "annoying"... eg:

    :Parameters:

    Shape

      Provided a shape.

      @PUBLIC

      a shape!

      ...

    :Returns:

    Shape

      This is returned.

      @PUBLIC

      a shape!

      ...

- rename `entry.filters` to `endpoint.filters`...
  **OR** actually move toward entry-based filtering
  (which is prolly better)

- when rendering long parameter attribute values, add ability to
  collapse it somehow...

- parse rst-literals as constants too, eg:

    foo : ( string | ``45.45`` )

  ==> the content must be YAML-parseable, and can be *any*
      YAML... cool.

- make the /describe/ root URL return an HTML page with all
  available options & formats (instead of redirecting to the
  default location)...
  maybe make it a sub-path? eg. /api/describe/ui
  which then let's you specify `showImpl`, `rstMax`, etc

- type registry improvements:
  - how to specify additional aliases in config? in documentation?
  - how to specify that some types are "undocumented"? eg. HTTPNotFound
  - class aliasing... eg CampaignPutSchema & CampaignGetSchema => Campaign

- support RAML? http://raml.org/
  swagger? https://en.wikipedia.org/wiki/Swagger_%28software%29

- migrate from `adict` to `aadict`

- support type definition and option promotion/demotion

  attr : X

    param1 : Y

  attr : X[!param2]

    param2 : Z

  ==> current text roles/directives:
    * doc.link
    * doc.copy
    * doc.import
    * doc.endpoint
      - regex
      - unmatched
      - link
  ==> new text roles/directives:
    * doc.type
      - regex
      - unmatched
      - link
    * doc.legend
    * doc.meta

  - naming rules:
    - initial-lowercase => primitive type
    - initial-uppercase => complex type
  - available options:
    - optional
    - required
    - r / read
    - w / write
    - c / create
    - ro / read-only
    - wo / write-only
    - co / create-only
    - nullable
    - default
    - default-to
  - merge all attributes from all same-name definitions
    => warn/error on collision
  - create ability to define types outside of endpoints
  - type aliases, eg `epoch` := `float`

  - support "special" "limits" section


- make the Entry object in entry.parsers support the mode where it
  has both a plain-text `.doc` and an rST `.rstdoc`, and it
  dynamically converts on demand (and expunges on `set`)... that way
  whatever you need is available...

- switch default `doc` encoding to UTF-8 (with option to override)
  so that something like this can be in the docstrings::

    Details in § `Foo Section`_.

  or submit patch to docutils that allows this:

    Details in :unicode:`U+000A7` `Foo Section`_.

- detect :doc.link:`...` links that don't have a target and fail or report
  error

- should the filters *augment* instead of *override* the system-defaults?
  ==> make it configurable?

- create a setting to auto-filter content based on labels, eg:
    labels: !internal ?public # == NOT `internal`, OPTIONAL `public`

- why are the pdfkit options being inserted into the HTML (instead of
  only in the HTML-for-PDF)?

- create a `Entry.labels` aadict that contains docorators
  ==> the value should be either True/False or the parameter in parenthesis
      if parenthesized.
  ==> make these go back and forth between Entry.classes prefixed with `doc-`...

- make the Dispatcher.walk() use generators instead of recursion...
  ==> reduces stack
  ==> **AND** could be used to solve the RestController issue #2 more elegantly

- add support for EPUB. model after:
    https://bitbucket.org/firesock/epubc/

- get rid of duplicate ids... for example, when two endpoints have
  the same-name parameter... you get:

    System Message: INFO/1 (application.rst, line 609); backlink
    Duplicate implicit target name: "username".

- when rendering rst *for end user consumption*, `:doc.*:` (and any
  other custom rendering instructions) must be converted to standard
  rST...

- in order to reduce verbosity, `:doc.copy:...:` should:
    - copy for structured data output (YAML, WADL, etc)
    - link for text output (HTML, etc)

- handle the scenario that all items in a "parameters" (or
  raises/returns) section are filtered out (and is thus empty,
  and shouldn't be displayed at all).

- flag :doc.*: references that point to invalid locations somehow

- move rst.Writer into docutils

- 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/
                |-- ...
                `-- ...

  ==> even better, don't restrict this algorithm just to the root,
      but apply it to any non-leaf node with just one sub-branch.

- 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` vs. `stage` etc...

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

- make the filters receive dup'd structures, so they are
  free to either modify the passed-in structure or return
  a whole new one ==> and document it!

- 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
