Fixed some sphinx warnings

1 files changed, 28 insertions, 52 deletions

diff --git a/docs/documentation.md b/docs/documentation.md
index 162caae..bd2b4ad 100644
--- a/docs/documentation.md
+++ b/docs/documentation.md
@@ -1,17 +1,15 @@
-Decorators for Humans
-----------------------------------
+# Decorators for Humans
 
 |Author | Michele Simionato|
 |---|---|
 |E-mail | michele.simionato@gmail.com|
-|Version| 5.0.9 (2021-05-16)|
+|Version| 5.0.9 (2021-09-11)|
 |Supports| Python 3.5, 3.6, 3.7, 3.8, 3.9|
 |Download page| http://pypi.python.org/pypi/decorator/5.0.9|
 |Installation| ``pip install decorator``|
 |License | BSD license|
 
-Introduction
------------------------------------------
+## Introduction
 
 The ``decorator`` module is over ten years old, but still alive and
 kicking. It is used by several frameworks (IPython, scipy, authkit,
@@ -22,8 +20,7 @@ supports Python versions greater than 3.4, versions 4.X supports Python
 versions back to 2.6; versions 3.X are able to support even Python 2.5 and
 2.4.
 
-What's New in version 5
------------------------
+## What's New in version 5
 
 Version 5 of the decorator module features a major simplification of
 the code base made possible by dropping support for Python releases
@@ -35,8 +32,7 @@ functions the traceback is nicer than it used to be. Moreover, it is
 now possible to mimic the behavior of decorators defined with
 ``functool.wraps``: see the section about the ``kwsyntax`` flag below.
 
-What's New in version 4
------------------------
+## What's New in version 4
 
 - **New documentation**
   There is now a single manual for all Python versions, so I took the
@@ -75,8 +71,7 @@ What's New in version 4
   From version 4.2 there is facility to define factories of decorators in
   a simple way, a feature requested by the users since a long time.
 
-Usefulness of decorators
-------------------------------------------------
+## Usefulness of decorators
 
 Python decorators are an interesting example of why syntactic sugar
 matters. In principle, their introduction in Python 2.4 changed
@@ -106,8 +101,7 @@ You may find the source code for all the examples
 discussed here in the ``documentation.py`` file, which contains
 the documentation you are reading in the form of doctests.
 
-Definitions
-------------------------------------
+## Definitions
 
 Technically speaking, any Python object which can be called with one argument
 can be used as a decorator. However, this definition is somewhat too large
@@ -136,8 +130,7 @@ obvious, especially if one wants to define proper decorators that
 can accept functions with any signature. A simple example will clarify
 the issue.
 
-Statement of the problem
-------------------------------
+## Statement of the problem
 
 A very common use case for decorators is the memoization of functions.
 A ``memoize`` decorator works by caching
@@ -146,7 +139,7 @@ the function is called with the same input parameters the result is retrieved
 from the cache and not recomputed.
 
 There are many implementations of ``memoize`` in
-https://wiki.python.org/moin/PythonDecoratorLibrary,
+http://www.python.org/moin/PythonDecoratorLibrary,
 but they do not preserve the signature. In recent versions of
 Python you can find a sophisticated ``lru_cache`` decorator
 in the standard library's ``functools``. Here I am just
@@ -222,8 +215,7 @@ TypeError: f1() takes exactly 1 positional argument (2 given)
 Notice that ``pydoc`` will give the right signature, but only in Python
 versions greater than 3.5.
 
-The solution
------------------------------------------
+## The solution
 
 The solution is to provide a generic factory of generators, which
 hides the complexity of making signature-preserving decorators
@@ -301,8 +293,7 @@ FullArgSpec(args=[], varargs=None, varkw=None, defaults=None, kwonlyargs=[], kwo
 
 ```
 
-A ``trace`` decorator
-------------------------------------------------------
+## A ``trace`` decorator
 
 Here is an example of how to define a simple ``trace`` decorator,
 which prints a message whenever the traced function is called:
@@ -361,8 +352,7 @@ FullArgSpec(args=['x', 'y'], varargs='args', varkw='kw', defaults=(1,), kwonlyar
 
 ```
 
-Function annotations
----------------------------------------------
+## Function annotations
 
 Python 3 introduced the concept of [function annotations](
 http://www.python.org/dev/peps/pep-3107/): the ability
@@ -416,9 +406,7 @@ This attribute exists for consistency with the behavior of
 Another attribute copied from the original function is ``__qualname__``,
 the qualified name. This attribute was introduced in Python 3.3.
 
-
-``decorator.decorator``
----------------------------------------------
+## ``decorator.decorator``
 
 It can become tedious to write a caller function (like the above
 ``_trace`` example) and then a trivial wrapper
@@ -468,8 +456,7 @@ calling func with args (), {}
 
 ```
 
-Mimicking the behavior of functools.wrap
-----------------------------------------
+## Mimicking the behavior of functools.wrap
 
 Often people are confused by the decorator module since, contrarily
 to ``functools.wraps`` in the standard library, it tries very hard
@@ -551,8 +538,7 @@ positional, i.e. they belongs to the ``args`` tuple and not to ``kwargs``:
 
 ```
 
-Decorator factories
--------------------------------------------
+## Decorator factories
 
 The `decorator` function can also be used to define factories of decorators,
 i.e. functions returning decorators. In general you can just write something
@@ -683,8 +669,7 @@ TypeError: You are decorating a non function: <class '__main__.User'>
 
 Be careful!
 
-``decorator(cls)``
---------------------------------------------
+## ``decorator(cls)``
 
 The ``decorator`` facility can also produce a decorator starting
 from a class with the signature of a caller. In such a case the
@@ -742,8 +727,7 @@ Here is the minimalistic usage:
 
 ```
 
-contextmanager
--------------------------------------
+## contextmanager
 
 Python's standard library has the ``contextmanager`` decorator,
 which converts a generator function into a ``GeneratorContextManager``
@@ -780,11 +764,11 @@ a ``__call__`` method, so that they can be used as decorators, like so:
 ```python
 >>> ba = before_after('BEFORE', 'AFTER')
 >>>
->>> @ba 
+>>> @ba
 ... def hello():
 ...     print('hello')
 ...
->>> hello() 
+>>> hello()
 BEFORE
 hello
 AFTER
@@ -808,8 +792,7 @@ instances of ``ContextManager``, a subclass of the standard library's
 an improved ``__call__`` method, which acts as a signature-preserving
 decorator.
 
-The ``FunctionMaker`` class
----------------------------------------------------------------
+## The ``FunctionMaker`` class
 
 The ``decorator`` module also provides a ``FunctionMaker`` class, which
 is able to generate on-the-fly functions
@@ -899,8 +882,7 @@ FullArgSpec(args=['a', 'b'], varargs=None, varkw=None, defaults=(None,), kwonlya
 
 ```
 
-Getting the source code
----------------------------------------------------
+## Getting the source code
 
 Internally, ``FunctionMaker.create`` uses ``exec`` to generate the
 decorated function. Therefore ``inspect.getsource`` will not work for
@@ -923,8 +905,7 @@ def factorial(n, acc=1):
 
 ```
 
-Dealing with third-party decorators
------------------------------------------------------------------
+## Dealing with third-party decorators
 
 Sometimes on the net you find some cool decorator that you would
 like to include in your code. However, more often than not, the cool
@@ -1047,8 +1028,7 @@ following:
 - returns a value without making a recursive call; or,
 - returns directly the result of a recursive call.
 
-Python 3.5 coroutines
------------------------
+## Python 3.5 coroutines
 
 I am personally not using Python 3.5 coroutines yet. However, some
 users requested support for coroutines and since version 4.1 the
@@ -1118,8 +1098,7 @@ function and the associate decorator was converting coroutines in coroutines;
 the caller in ``coro_to_func`` is a regular function and converts
 coroutines -> functions.
 
-Multiple dispatch
--------------------------------------------
+## Multiple dispatch
 
 There has been talk of implementing multiple dispatch functions
 (i.e. "generic functions") in Python for over ten years. Last year,
@@ -1315,8 +1294,7 @@ product of the class precedence lists (or *Method Resolution Orders*,
 [MRO](http://www.python.org/2.3/mro.html) for short) of ``StrongRock``
  and ``Scissors``, respectively.
 
-Generic functions and virtual ancestors
--------------------------------------------------
+## Generic functions and virtual ancestors
 
 In Python, generic functions are complicated by the existence of
 "virtual ancestors": superclasses which are not in the class hierarchy.
@@ -1535,8 +1513,7 @@ call-next-method in Lisp, or to ``super`` in Python.
 Finally, let me notice that the decorator module implementation does
 not use any cache, whereas the ``singledispatch`` implementation does.
 
-Caveats and limitations
--------------------------------------------
+## Caveats and limitations
 
 In the present implementation, decorators generated by ``decorator``
 can only be used on user-defined Python functions, methods or coroutines.
@@ -1650,8 +1627,7 @@ than the function ``f`` here, so the real life performance penalty
 *could* be negligible.  As always, the only way to know if there is a
 penalty in your specific use case is to measure it.
 
-LICENSE (2-clause BSD)
----------------------------------------------
+## LICENSE (2-clause BSD)
 
 Copyright (c) 2005-2020, Michele Simionato
 All rights reserved.
@@ -1682,4 +1658,4 @@ DAMAGE.
 
 If you use this software and you are happy with it, consider sending me a
 note, just to gratify my ego. On the other hand, if you use this software and
-you are unhappy with it, send me a patch!
+you are unhappy with it, send me a patch!
\ No newline at end of file