From 7bd4bd1f7f449a4eb4214ff892b9c042a432336d Mon Sep 17 00:00:00 2001 From: Jonathan Jacobs Date: Fri, 16 May 2014 12:24:35 +0200 Subject: [PATCH] Take our own docs style advice. --- README.rst | 3 ++- docs/api.rst | 9 +++++---- docs/index.rst | 18 ++++++++++-------- docs/query.rst | 3 ++- docs/resource.rst | 5 +++-- docs/route.rst | 9 +++++---- 6 files changed, 27 insertions(+), 20 deletions(-) diff --git a/README.rst b/README.rst index 3f8c7ba..f7df8b6 100644 --- a/README.rst +++ b/README.rst @@ -1,3 +1,4 @@ +===================================== Spinneret: Twisted Web's Silk Spinner ===================================== @@ -23,7 +24,7 @@ See http://github.com/jonathanj/txspinneret for development. Installation ------------- +============ .. code-block:: console diff --git a/docs/api.rst b/docs/api.rst index 0298e37..3cc292a 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,8 +1,9 @@ +================= API Documentation ================= Resource routing ----------------- +================ .. automodule:: txspinneret.route :members: @@ -14,7 +15,7 @@ Resource routing Query arguments ---------------- +=============== .. automodule:: txspinneret.query :members: @@ -26,7 +27,7 @@ Query arguments Utility resources ------------------ +================= .. automodule:: txspinneret.resource :members: @@ -37,7 +38,7 @@ Utility resources Interfaces ----------- +========== .. automodule:: txspinneret.interfaces :members: diff --git a/docs/index.rst b/docs/index.rst index 665186e..b07abcc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,6 +3,7 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +===================================== Spinneret: Twisted Web's Silk Spinner ===================================== @@ -10,7 +11,7 @@ Release v\ |release|. What is this? -------------- +============= Spinneret is a collection of higher-level utility classes and functions to make writing complex Twisted Web applications far simpler, it is designed to easily @@ -19,7 +20,7 @@ integrate with existing Twisted Web projects for things like the improved Why is this one different? --------------------------- +========================== While I think `Klein`_ is a fantastic library—and a terrific source of inspiration—there are some fundamental aspects I disagree with, not to mention @@ -46,7 +47,7 @@ Or to install the latest development version: Documentation -------------- +============= .. toctree:: :maxdepth: 2 @@ -63,10 +64,11 @@ API documentation api -Indices and tables -================== -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +Contributing +============ + +.. toctree:: + :maxdepth: 2 + contributing diff --git a/docs/query.rst b/docs/query.rst index 0b49bc7..3d45eb6 100644 --- a/docs/query.rst +++ b/docs/query.rst @@ -1,5 +1,6 @@ .. py:currentmodule:: txspinneret.query +=============== Query Arguments =============== @@ -12,7 +13,7 @@ The tedious process of processing query arguments usually follows this pattern: Parsing query arguments ------------------------ +======================= This small set of utility functions can relieve some of that pain, for example assume the query string is diff --git a/docs/resource.rst b/docs/resource.rst index d182499..289ab48 100644 --- a/docs/resource.rst +++ b/docs/resource.rst @@ -1,5 +1,6 @@ .. py:currentmodule:: txspinneret.resource +================== Resource Utilities ================== @@ -8,7 +9,7 @@ with any existing `IResource` implementations. More featureful resources -------------------------- +========================= `ISpinneretResource` is cut-down version of `IResource` that allows child location (via `ISpinneretResource.locateChild`) and rendering (via the normal @@ -27,7 +28,7 @@ And secondly, a `list` of remaining path segments to be processed. Negotiating resources based on ``Accept`` ------------------------------------------ +========================================= When building an API, in particular, you may want to negotiate the resource that best fits what the client is willing to accept, as specified in the diff --git a/docs/route.rst b/docs/route.rst index d2c8c88..777d763 100644 --- a/docs/route.rst +++ b/docs/route.rst @@ -1,5 +1,6 @@ .. py:currentmodule:: txspinneret.route +=========== URL Routing =========== @@ -17,7 +18,7 @@ is only possible to specify relative routes. Router basics -------------- +============= `Router.route` will match a URL route exactly, meaning that every route component must match the respective segment in the URL path; eg. @@ -42,7 +43,7 @@ other parts of Spinneret or Twisted Web. Special routes --------------- +============== There are two routes—particularly in the case of nested routers—that may not be obvious at first: The null root and the empty route. @@ -70,7 +71,7 @@ with ``@router.route()`` (the null route.) Matcher basics --------------- +============== `txspinneret.route` contains some basic matchers such as `Any` (which is a synonym for `Text`) and `Integer`. These matchers are simple factory @@ -81,7 +82,7 @@ match.) Writing your own matchers to suit your needs is encouraged. An example router ------------------ +================= .. literalinclude:: examples/user_router.py