Documentation: Reference docs WIP tracking issue

[peterschutt]

This issue is for tracking work still to be completed for rollout of the reference api docs.

[peterschutt]

The following reference doc pages are incomplete (relative to docs/reference/):

• [x] app.md - include DEFAULT_CACHE_CONFIG and cross-ref in Starlite.__init__ args
• [x] cache.md
  • [x] CacheBackendProtocol - add abstract methods
• [x] config.md - fix ordering so same as module
• [x] connection.md
  • [x] Request - docstrings for properties, include properties and json() method
  • [x] WebSocket - docstrings for properties, include properties and receive_json() and send_json() methods
  • [ ] consider factoring out a common Connection base class with the properties defined and documented.
• [x] controller.md - complete __init__ docstring and include class variables
• [x] datastructures.md - document and include all
• [x] dto.md
  • [x] DTO - class docstring, class var docstrings, include class vars, from_model_instance(), from_model_instance_async(), and to_model_instance().
  • [x] DTOFactory - document __init__, include __init__ and __call__
• [x] exceptions.md
  • [x] exceptions.py: docstrings for each exception type and add name to .md
  • [x] utils.py: create_exception_response()
• [x] enums.md - add all from enums.py
• [x] handlers.md
  • [x] asgi.py
    • [x] docstring for ASGIRouteHandler.__init__()
    • [x] add ASGIRouteHandler to handlers.md and include __init__()
    • [x] add asgi to handlers.md
  • [x] http.py
    • [x] docstring for HTTPRouteHandler.__init__()
    • [x] add HTTPRouteHandler to handlers.md and include __init__()
    • [x] add route to handlers.md
    • [ ] slim docstrings for each of the semantic handler decorators and include in handlers.md
  • [x] `websocket.py
    • [x] Add WebsocketRouteHandler and websocket to handlers.md
• [x] logging.md
  • [x] __init__.py
    • [x] docstring for LoggingConfig class
    • [x] docstrings for LoggingConfig class vars
    • [x] include LoggingConfig in logging.md
  • [x] picologging.py
    • [x] docstring for QueueListenerHandler.__init__()
    • [x] add QueueListenerHandler to logging.md and include __init__
  • [x] standard.py - do same as for picologging.py
• [x] middleware.md
  • [x] authentication.py
    • [x] add docstring for AbstractAuthenticationMiddleware.__init__()
    • [ ] we should probably use utils.create_exception_response() in AbstractAuthenticationMiddleware.create_error_response()
    • [x] docstring for AbstractAuthenticationMiddleware.create_error_response()
    • [x] docstring for AbstractAuthenticationMiddleware.authenticate_request()
    • [x] add AbstractAuthenticationMiddleware to middleware.md and include __init__, create_error_response() and authenticate_request()
  • [x] csrf.py
    • [x] Add CSRFMiddleware to middleware.md
• [x] openapi.md
  • [x] controller.py
    • [x] docstring for OpenAPIController class
    • [x] docstrings for OpenAPIController class vars
• [x] params.md
  • [ ] try and work out why black fails to format when separate_signature: true
  • [x] full docstrings for Parameter, Body and Dependency
  • [x] add each of above to params.md
• [x] plugins.md
  • [ ] base.py
    • [x] add class docstring to PluginProtocol
    • [x] complete docstrings for PluginProtocol abstract methods
    • [x] add PluginProtocol to plugins.md and include all abstract methods
  • [x] piccolo_orm.py
    • [x] class docstring for PiccoloORMPlugin and add to plugins.md
  • [x] sql_alchemy.py
    • [x] same as piccolo
  • [x] tortoise.py
    • [x] same as piccolo
• [ ] response.md
  • [ ] include __init__ and serializer() for Response
  • [ ] add TemplateResponse to response.md and include __init__

[Goldziher]

well two of these are done 😉

[peterschutt]

Other things TODO:

• [x] update the contributing docs with instructions for reference docs as part of contributions
• [x] change instructions in CONTRIBUTING.md for serving docs locally - the docker approach won't work unless we run our own container with the extra dependencies, or find one to use. mkdocs serve has been working fine for me.
• [ ] remove the WIP admonition once complete
• [ ] once all interfaces are included, do a final sweep to look for missing cross-references.

[peterschutt]

This is wrong: https://github.com/starlite-api/starlite/blob/db1eab98c50c1ed9fa176e7e06c3b34ddee68197/starlite/app.py#L123-L125

[peterschutt]

Documented in wrong location:

https://github.com/starlite-api/starlite/blob/db1eab98c50c1ed9fa176e7e06c3b34ddee68197/docs/reference/enums.md?plain=1#L15-L19

It's defined in config.py