Update routing documentation (#1738)

Works towards #1531 

Some parts of the old outing docs will need to be included on the
`parameters` and `swagger-ui` pages which we still need to add.

tox.ini

@@ -4,7 +4,7 @@ rst-roles=class,mod,obj
 # https://black.readthedocs.io/en/stable/guides/using_black_with_other_tools.html#flake8
 # Longest docstring in current code base
 max-line-length=137
-extend-ignore=E203
+extend-ignore=E203,RST303
 
 [tox]
 isolated_build = True