DOC: make some github issues into links, doc fixes (GH-4060)

* DOC: make some github issues into links, doc fixes
* add a doc-requirements.txt for building docs
* use ':issue:' domains for github issues

14 files changed, 161 insertions, 121 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index 10d47a5de..7434a45cf 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -8,53 +8,53 @@ Cython Changelog
 Features added
 --------------
 
-* ``__class_getitem__`` (PEP-560) is supported for cdef classes.
-  Patch by Kmol Yuan.  (Github issue #3764)
+* ``__class_getitem__`` (`PEP-560`_) is supported for cdef classes.
+  Patch by Kmol Yuan.  (Github issue :issue:`3764`)
 
 * ``cython.array`` supports simple, non-strided views.
-  (Github issue #3775)
+  (Github issue :issue:`3775`)
 
 * The destructor is now called for fields in C++ structs.
-  Patch by David Woods.  (Github issue #3226)
+  Patch by David Woods.  (Github issue :issue:`3226`)
 
 * ``asyncio.iscoroutinefunction()`` now recognises coroutine functions
   also when compiled by Cython.
-  Patch by Pedro Marques da Luz.  (Github issue #2273)
+  Patch by Pedro Marques da Luz.  (Github issue :issue:`2273`)
 
 * ``float(…)`` is optimised for string arguments (str/bytes/bytearray).
 
 * Docstrings of ``cpdef`` enums are now copied to the enum class.
-  Patch by matham.  (Github issue #3805)
+  Patch by matham.  (Github issue :issue:`3805`)
 
 * The type ``cython.Py_hash_t`` is available in Python mode.
 
 * The value ``PyBUF_MAX_NDIM`` was added to the ``cpython.buffer`` module.
-  Patch by John Kirkham.  (Github issue #3811)
+  Patch by John Kirkham.  (Github issue :issue:`3811`)
 
 Bugs fixed
 ----------
 
 * Inline functions and other code in ``.pxd`` files could accidentally
   inherit the compiler directives of the ``.pyx`` file that imported them.
-  Patch by David Woods.  (Github issue #1071)
+  Patch by David Woods.  (Github issue :issue:`1071`)
 
 * ``ndarray.shape`` failed to compile with Pythran and recent NumPy.
-  Patch by Serge Guelton.  (Github issue #3762)
+  Patch by Serge Guelton.  (Github issue :issue:`3762`)
 
 * Casting to ctuples is now allowed.
-  Patch by David Woods.  (Github issue #3808)
+  Patch by David Woods.  (Github issue :issue:`3808`)
 
 * A C compiler warning about unused code was resolved.
-  (Github issue #3763)
+  (Github issue :issue:`3763`)
 
 * A C compiler warning about enum value casting was resolved in GCC.
-  (Github issue #2749)
+  (Github issue :issue:`2749`)
 
 * A compile failure for C++ enums in Py3.4 / MSVC was resolved.
-  Patch by Ashwin Srinath.  (Github issue #3782)
+  Patch by Ashwin Srinath.  (Github issue :issue:`3782`)
 
 * The Cython ``CodeWriter`` mishandled no-argument ``return`` statements.
-  Patch by Tao He.  (Github issue #3795)
+  Patch by Tao He.  (Github issue :issue:`3795`)
 
 
 3.0.0 alpha 6 (2020-07-31)
@@ -72,51 +72,51 @@ Features added
   0.29.20), or the reversed method (``__radd__``) can be implemented in
   addition to an existing two-sided operator method (``__add__``) to get a
   backwards compatible implementation.
-  (Github issue #2056)
+  (Github issue :issue:`2056`)
 
 * No/single argument functions now accept keyword arguments by default in order
   to comply with Python semantics.  The marginally faster calling conventions
   ``METH_NOARGS`` and ``METH_O`` that reject keyword arguments are still available
   with the directive ``@cython.always_allow_keywords(False)``.
-  (Github issue #3090)
+  (Github issue :issue:`3090`)
 
 * For-in-loop iteration over ``bytearray`` and memory views is optimised.
-  Patch by David Woods.  (Github issue #2227)
+  Patch by David Woods.  (Github issue :issue:`2227`)
 
 * Type inference now works for memory views and slices.
-  Patch by David Woods.  (Github issue #2227)
+  Patch by David Woods.  (Github issue :issue:`2227`)
 
 * The ``@returns()`` decorator propagates exceptions by default for suitable C
   return types when no ``@exceptval()`` is defined.
-  (Github issues #3625, #3664)
+  (Github issues :issue:`3625`, :issue:`3664`)
 
 * A low-level inline function ``total_seconds(timedelta)`` was added to
   ``cpython.datetime`` to bypass the Python method call.  Note that this function
   is not guaranteed to give exactly the same results for very large time intervals.
-  Patch by Brock Mendel.  (Github issue #3616)
+  Patch by Brock Mendel.  (Github issue :issue:`3616`)
 
 * Type inference now understands that ``a, *b = x`` assigns a list to ``b``.
 
 * Limited API support was improved.
-  Patches by Matthias Braun.  (Github issues #3693, #3707)
+  Patches by Matthias Braun.  (Github issues :issue:`3693`, :issue:`3707`)
 
 * The Cython ``CodeWriter`` can now handle more syntax constructs.
-  Patch by Tao He.  (Github issue #3514)
+  Patch by Tao He.  (Github issue :issue:`3514`)
 
 Bugs fixed
 ----------
 
 * The construct ``for x in cpp_function_call()`` failed to compile.
-  Patch by David Woods.  (Github issue #3663)
+  Patch by David Woods.  (Github issue :issue:`3663`)
 
 * C++ references failed to compile when used as Python object indexes.
-  Patch by David Woods.  (Github issue #3754)
+  Patch by David Woods.  (Github issue :issue:`3754`)
 
 * The C++ ``typeid()`` function was allowed in C mode.
-  Patch by Celelibi.  (Github issue #3637)
+  Patch by Celelibi.  (Github issue :issue:`3637`)
 
 * ``repr()`` was assumed to return ``str`` instead of ``unicode`` with ``language_level=3``.
-  (Github issue #3736)
+  (Github issue :issue:`3736`)
 
 * Includes all bug-fixes from the 0.29.21 release.
 
@@ -133,43 +133,42 @@ Other changes
   homeless builtins, to help with debugging, and in order to avoid a CPython
   warning according to https://bugs.python.org/issue20204
 
-
 3.0.0 alpha 5 (2020-05-19)
 ==========================
 
 Features added
 --------------
 
-* ``.pxd`` files can now be versioned by adding an extension like "``.cython-30.pxd``"
-  to prevent older Cython versions (than 3.0 in this case) from picking them up.
-  (Github issue #3577)
+* ``.pxd`` files can now be :ref:`versioned <versioning>` by adding an
+  extension like "``.cython-30.pxd``" to prevent older Cython versions (than
+  3.0 in this case) from picking them up.  (Github issue :issue:`3577`)
 
 * Several macros/functions declared in the NumPy API are now usable without
   holding the GIL.
 
-* ``libc.math`` was extended to include all C99 function declarations.
-  Patch by Dean Scarff.  (Github issue #3570)
+* `libc.math` was extended to include all C99 function declarations.
+  Patch by Dean Scarff.  (Github issue :issue:`3570`)
 
 Bugs fixed
 ----------
 
 * Several issues with arithmetic overflow handling were resolved, including
   undefined behaviour in C.
-  Patch by Sam Sneddon.  (Github issue #3588)
+  Patch by Sam Sneddon.  (Github issue :issue:`3588`)
 
 * The improved GIL handling in ``nogil`` functions introduced in 3.0a3
   could fail to acquire the GIL in some cases on function exit.
-  (Github issue #3590 etc.)
+  (Github issue :issue:`3590` etc.)
 
 * A reference leak when processing keyword arguments in Py2 was resolved,
   that appeared in 3.0a1.
-  (Github issue #3578)
+  (Github issue :issue:`3578`)
 
 * The outdated getbuffer/releasebuffer implementations in the NumPy
   declarations were removed so that buffers declared as ``ndarray``
   now use the normal implementation in NumPy.
 
-* Includes all bug-fixes from the 0.29.18 release.
+* Includes all bug-fixes from the :ref:0.29.18 release.
 
 
 3.0.0 alpha 4 (2020-05-05)
@@ -203,15 +202,15 @@ Bugs fixed
   C-API functions with an error held.
 
 * Complex buffer item types of structs of arrays could fail to validate.
-  Patch by Leo and smutch.  (Github issue #1407)
+  Patch by Leo and smutch.  (Github issue :issue:`1407`)
 
 * When importing the old Cython ``build_ext`` integration with distutils, the
   additional command line arguments leaked into the regular command.
-  Patch by Kamekameha.  (Github issue #2209)
+  Patch by Kamekameha.  (Github issue :issue:`2209`)
 
 * The improved GIL handling in ``nogil`` functions introduced in 3.0a3
   could generate invalid C code.
-  (Github issue #3558)
+  (Github issue :issue:`3558`)
 
 * ``PyEval_InitThreads()`` is no longer used in Py3.7+ where it is a no-op.
 
@@ -221,7 +220,7 @@ Other changes
 -------------
 
 * The C property feature has been rewritten and now requires C property methods
-  to be declared ``inline``.
+  to be declared ``inline`` (:issue:`3571`).
 
 
 3.0.0 alpha 3 (2020-04-27)
@@ -232,17 +231,17 @@ Features added
 
 * ``nogil`` functions now avoid acquiring the GIL on function exit if possible
   even if they contain ``with gil`` blocks.
-  (Github issue #3554)
+  (Github issue :issue:`3554`)
 
 * Python private name mangling now falls back to unmangled names for non-Python
   globals, since double-underscore names are not uncommon in C.  Unmangled Python
   names are also still found as a legacy fallback but produce a warning.
-  Patch by David Woods.  (Github issue #3548)
+  Patch by David Woods.  (Github issue :issue:`3548`)
 
 Bugs fixed
 ----------
 
-* Includes all bug-fixes from the 0.29.17 release.
+* Includes all bug-fixes from the :ref:0.29.17 release.
 
 
 3.0.0 alpha 2 (2020-04-23)
@@ -253,29 +252,29 @@ Features added
 
 * ``std::move()`` is now used in C++ mode for internal temp variables to
   make them work without copying values.
-  Patch by David Woods.  (Github issues #3253, 1612)
+  Patch by David Woods.  (Github issues :issue:`3253`, :issue:`1612`)
 
-* ``__class_getitem__`` is supported for types on item access (PEP-560).
-  Patch by msg555.  (Github issue #2753)
+* ``__class_getitem__`` is supported for types on item access (`PEP-560`_).
+  Patch by msg555.  (Github issue :issue:`2753`)
 
-* The simplified Py3.6 customisation of class creation is implemented (PEP-487).
+* The simplified Py3.6 customisation of class creation is implemented (`PEP-487`_).
   (Github issue #2781)
 
 * Conditional blocks in Python code that depend on ``cython.compiled`` are
   eliminated at an earlier stage, which gives more freedom in writing
   replacement Python code.
-  Patch by David Woods.  (Github issue #3507)
+  Patch by David Woods.  (Github issue :issue:`3507`)
 
 * ``numpy.import_array()`` is automatically called if ``numpy`` has been cimported
   and it has not been called in the module code.  This is intended as a hidden
   fail-safe so user code should continue to call ``numpy.import_array``.
-  Patch by David Woods.  (Github issue #3524)
+  Patch by David Woods.  (Github issue :issue:`3524`)
 
 * The Cython AST code serialiser class ``CodeWriter`` in ``Cython.CodeWriter``
   supports more syntax nodes.
 
 * The fastcall/vectorcall protocols are used for several internal Python calls.
-  (Github issue #3540)
+  (Github issue :issue:`3540`)
 
 Bugs fixed
 ----------
@@ -283,23 +282,23 @@ Bugs fixed
 * With ``language_level=3/3str``, Python classes without explicit base class
   are now new-style (type) classes also in Py2.  Previously, they were created
   as old-style (non-type) classes.
-  (Github issue #3530)
+  (Github issue :issue:`3530`)
 
 * C++ ``typeid()`` failed for fused types.
-  Patch by David Woods.  (Github issue #3203)
+  Patch by David Woods.  (Github issue :issue:`3203`)
 
 * ``__arg`` argument names in methods were not mangled with the class name.
-  Patch by David Woods.  (Github issue #1382)
+  Patch by David Woods.  (Github issue :issue:`1382`)
 
 * Creating an empty unicode slice with large bounds could crash.
-  Patch by Sam Sneddon.  (Github issue #3531)
+  Patch by Sam Sneddon.  (Github issue :issue:`3531`)
 
 * Decoding an empty bytes/char* slice with large bounds could crash.
-  Patch by Sam Sneddon.  (Github issue #3534)
+  Patch by Sam Sneddon.  (Github issue :issue:`3534`)
 
 * Temporary buffer indexing variables were not released and could show up in
   C compiler warnings, e.g. in generators.
-  Patch by David Woods.  (Github issues #3430, #3522)
+  Patch by David Woods.  (Github issues :issue:`3430`, :issue:`3522`)
 
 * Several C compiler warnings were fixed.
 
@@ -310,113 +309,115 @@ Bugs fixed
 Features added
 --------------
 
-* Cython functions now use the PEP-590 vectorcall protocol in Py3.7+.
-  Patch by Jeroen Demeyer.  (Github issue #2263)
+* Cython functions now use the `PEP-590`_ vectorcall protocol in Py3.7+.
+  Patch by Jeroen Demeyer.  (Github issue :issue:`2263`)
 
-* Unicode identifiers are supported in Cython code (PEP 3131).
-  Patch by David Woods.  (Github issue #2601)
+* Unicode identifiers are supported in Cython code (`PEP-3131`_).
+  Patch by David Woods.  (Github issue :issue:`2601`)
 
 * Unicode module names and imports are supported.
-  Patch by David Woods.  (Github issue #3119)
+  Patch by David Woods.  (Github issue :issue:`3119`)
 
-* Annotations are no longer parsed, keeping them as strings following PEP-563.
-  Patch by David Woods.  (Github issue #3285)
+* Annotations are no longer parsed, keeping them as strings following `PEP-563`_.
+  Patch by David Woods.  (Github issue :issue:`3285`)
 
 * Preliminary support for the CPython's ``Py_LIMITED_API`` (stable ABI) is
   available by setting the  ``CYTHON_LIMITED_API`` C macro.  Note that the
   support is currently in an early stage and many features do not yet work.
-  Patches by Eddie Elizondo and David Woods.  (Github issues #3223, #3311, #3501)
+  Patches by Eddie Elizondo and David Woods.  (Github issues :issue:`3223`,
+  :issue:`3311`, :issue:`3501`)
 
 * The dispatch to fused functions is now linear in the number of arguments,
   which makes it much faster, often 2x or more, and several times faster for
   larger fused types with many specialisations.
-  Patch by will-ca.  (Github issue #1385)
+  Patch by will-ca.  (Github issue :issue:`1385`)
 
 * ``with gil/nogil`` statements can be conditional based on compile-time
   constants, e.g. fused type checks.
-  Patch by Noam Hershtig.  (Github issue #2579)
+  Patch by Noam Hershtig.  (Github issue :issue:`2579`)
 
 * ``const`` can be used together with fused types.
-  Patch by Thomas Vincent.  (Github issue #1772)
+  Patch by Thomas Vincent.  (Github issue :issue:`1772`)
 
 * Reimports of already imported modules are substantially faster.
-  (Github issue #2854)
+  (Github issue :issue:`2854`)
 
-* Positional-only arguments are supported in Python functions (PEP-570).
-  Patch by Josh Tobin.  (Github issue #2915)
+* Positional-only arguments are supported in Python functions (`PEP-570`_).
+  Patch by Josh Tobin.  (Github issue :issue:`2915`)
 
 * The ``volatile`` C modifier is supported in Cython code.
   Patch by Jeroen Demeyer.  (Github issue #1667)
 
 * ``@cython.trashcan(True)`` can be used on an extension type to enable the
-  CPython trashcan. This allows deallocating deeply recursive objects without
-  overflowing the stack.  Patch by Jeroen Demeyer.  (Github issue #2842)
+  CPython :ref:`trashcan`. This allows deallocating deeply recursive objects
+  without overflowing the stack. Patch by Jeroen Demeyer.  (Github issue :issue:`2842`)
 
 * Inlined properties can be defined for external extension types.
-  Patch by Matti Picus.  (Github issue #2640)
+  Patch by Matti Picus. (Github issue :issue:`2640`, redone later in :issue:`3571`)
 
 * The ``str()`` builtin now calls ``PyObject_Str()`` instead of going
   through a Python call.
-  Patch by William Ayd.  (Github issue #3279)
+  Patch by William Ayd.  (Github issue :issue:`3279`)
 
 * String concatenation can now happen in place if possible, by extending the
   existing string rather than always creating a new one.
-  Patch by David Woods.  (Github issue #3453)
+  Patch by David Woods.  (Github issue :issue:`3453`)
 
 * Multiplication of Python numbers with small constant integers is faster.
-  (Github issue #2808)
+  (Github issue :issue:`2808`)
 
 * Some list copying is avoided internally when a new list needs to be created
   but we already have a fresh one.
-  (Github issue #3494)
+  (Github issue :issue:`3494`)
 
 * Extension types that do not need their own ``tp_new`` implementation (because
   they have no object attributes etc.) directly inherit the implementation of
   their parent type if possible.
-  (Github issue #1555)
+  (Github issue :issue:`1555`)
 
 * The attributes ``gen.gi_frame`` and ``coro.cr_frame`` of Cython compiled
   generators and coroutines now return an actual frame object for introspection.
-  (Github issue #2306)
+  (Github issue :issue:`2306`)
 
 * Several declarations in ``cpython.*``, ``libc.*`` and ``libcpp.*`` were added.
   Patches by Jeroen Demeyer, Matthew Edwards, Chris Gyurgyik, Jerome Kieffer
   and Zackery Spytz.
-  (Github issues #3468, #3332, #3202, #3188, #3179, #2891, #2826, #2713)
+  (Github issues :issue:`3468`, :issue:`3332`, :issue:`3202`, :issue:`3188`,
+  :issue:`3179`, :issue:`2891`, :issue:`2826`, :issue:`2713`)
 
 * Deprecated NumPy API usages were removed from ``numpy.pxd``.
-  Patch by Matti Picus.  (Github issue #3365)
+  Patch by Matti Picus.  (Github issue :issue:`3365`)
 
 * ``cython.inline()`` now sets the ``NPY_NO_DEPRECATED_API=NPY_1_7_API_VERSION``
   C macro automatically when ``numpy`` is imported in the code, to avoid C compiler
   warnings about deprecated NumPy C-API usage.
 
 * The builtin ``abs()`` function can now be used on C numbers in nogil code.
-  Patch by Elliott Sales de Andrade.  (Github issue #2748)
+  Patch by Elliott Sales de Andrade.  (Github issue :issue:`2748`)
 
-* PEP-479 (``generator_stop``) is now enabled by default with language level 3.
-  (Github issue #2580)
+* `PEP-479`_ (``generator_stop``) is now enabled by default with language level 3.
+  (Github issue :issue:`2580`)
 
 * The ``cython.view.array`` type supports inheritance.
-  Patch by David Woods.  (Github issue #3413)
+  Patch by David Woods.  (Github issue :issue:`3413`)
 
 * Code annotation accepts a new debugging argument ``--annotate-fullc`` that
   will include the complete syntax highlighted C file in the HTML output.
-  (Github issue #2855)
+  (Github issue :issue:`2855`)
 
 * ``--no-capture`` added to ``runtests.py`` to prevent stdout/stderr capturing
   during srctree tests.
-  Patch by Matti Picus.  (Github issue #2701)
+  Patch by Matti Picus.  (Github issue :issue:`2701`)
 
 * ``--no-docstrings`` option added to ``cythonize`` script.
-  Original patch by mo-han.  (Github issue #2889)
+  Original patch by mo-han.  (Github issue :issue:`2889`)
 
 * ``cygdb`` gives better error messages when it fails to initialise the
   Python runtime support in gdb.
-  Patch by Volker Weissmann.  (Github issue #3489)
+  Patch by Volker Weissmann.  (Github issue :issue:`3489`)
 
 * The Pythran ``shape`` attribute is supported.
-  Patch by Serge Guelton.  (Github issue #3307)
+  Patch by Serge Guelton.  (Github issue :issue:`3307`)
 
 Bugs fixed
 ----------
@@ -428,7 +429,7 @@ Bugs fixed
 
 * Fused argument types were not correctly handled in type annotations and
   ``cython.locals()``.
-  Patch by David Woods.  (Github issues #3391, #3142)
+  Patch by David Woods.  (Github issues :issue:`3391`, :issue:`3142`)
 
 * Diverging from the usual behaviour, ``len(memoryview)``, ``len(char*)``
   and ``len(Py_UNICODE*)`` returned an unsigned ``size_t`` value.  They now
@@ -437,59 +438,59 @@ Bugs fixed
 * Nested dict literals in function call kwargs could incorrectly raise an
   error about duplicate keyword arguments, which are allowed when passing
   them from dict literals.
-  (Github issue #2963)
+  (Github issue :issue:`2963`)
 
 * Item access (subscripting) with integer indices/keys always tried the
   Sequence protocol before the Mapping protocol, which diverged from Python
   semantics.  It now passes through the Mapping protocol first when supported.
-  (Github issue #1807)
+  (Github issue :issue:`1807`)
 
 * Name lookups in class bodies no longer go through an attribute lookup.
-  Patch by Jeroen Demeyer.  (Github issue #3100)
+  Patch by Jeroen Demeyer.  (Github issue :issue:`3100`)
 
 * Broadcast assignments to a multi-dimensional memory view slice could end
   up in the wrong places when the underlying memory view is known to be
   contiguous but the slice is not.
-  (Github issue #2941)
+  (Github issue :issue:`2941`)
 
 * Pickling unbound methods of Python classes failed.
-  Patch by Pierre Glaser.  (Github issue #2972)
+  Patch by Pierre Glaser.  (Github issue :issue:`2972`)
 
 * The ``Py_hash_t`` type failed to accept arbitrary "index" values.
-  (Github issue #2752)
+  (Github issue :issue:`2752`)
 
 * The first function line number of functions with decorators pointed to the
   signature line and not the first decorator line, as in Python.
-  Patch by Felix Kohlgrüber.  (Github issue #2536)
+  Patch by Felix Kohlgrüber.  (Github issue :issue:`2536`)
 
 * Constant integer expressions that used a negative exponent were evaluated
   as integer 0 instead of the expected float value.
-  Patch by Kryštof Pilnáček.  (Github issue #2133)
+  Patch by Kryštof Pilnáček.  (Github issue :issue:`2133`)
 
 * The ``cython.declare()`` and ``cython.cast()`` functions could fail in pure mode.
-  Patch by Dmitry Shesterkin.  (Github issue #3244)
+  Patch by Dmitry Shesterkin.  (Github issue :issue:`3244`)
 
 * ``__doc__`` was not available inside of the class body during class creation.
-  (Github issue #1635)
+  (Github issue :issue:`1635`)
 
 * Setting ``language_level=2`` in a file did not work if ``language_level=3``
   was enabled globally before.
-  Patch by Jeroen Demeyer.  (Github issue #2791)
+  Patch by Jeroen Demeyer.  (Github issue :issue:`2791`)
 
 * ``__init__.pyx`` files were not always considered as package indicators.
-  (Github issue #2665)
+  (Github issue :issue:`2665`)
 
 * Compiling package ``__init__`` files could fail under Windows due to an
-  undefined export symbol.  (Github issue #2968)
+  undefined export symbol.  (Github issue :issue:`2968`)
 
 * A C compiler cast warning was resolved.
-  Patch by Michael Buesch.  (Github issue #2775)
+  Patch by Michael Buesch.  (Github issue :issue:`2775`)
 
 * Binding staticmethods of Cython functions were not behaving like Python methods.
-  Patch by Jeroen Demeyer.  (Github issue #3106, #3102)
+  Patch by Jeroen Demeyer.  (Github issue :issue:`3106`, :issue:`3102`)
 
 * Memoryviews failed to compile when the ``cache_builtins`` feature was disabled.
-  Patch by David Woods.  (Github issue #3406)
+  Patch by David Woods.  (Github issue :issue:`3406`)
 
 Other changes
 -------------
@@ -498,39 +499,46 @@ Other changes
   but with ``str`` literals (also in Python 2.7).  This is a backwards incompatible
   change from the previous default of Python 2 semantics.  The previous behaviour
   is available through the directive ``language_level=2``.
-  (Github issue #2565)
+  (Github issue :issue:`2565`)
 
 * Cython no longer generates ``__qualname__`` attributes for classes in Python
   2.x since they are problematic there and not correctly maintained for subclasses.
-  Patch by Jeroen Demeyer.  (Github issue #2772)
+  Patch by Jeroen Demeyer.  (Github issue :issue:`2772`)
 
 * Source file fingerprinting now uses SHA-1 instead of MD5 since the latter
   tends to be slower and less widely supported these days.
-  (Github issue #2790)
+  (Github issue :issue:`2790`)
 
 * The long deprecated include files ``python_*``, ``stdio``, ``stdlib`` and
   ``stl`` in ``Cython/Includes/Deprecated/`` were removed.  Use the ``libc.*``
   and ``cpython.*`` pxd modules instead.
-  Patch by Jeroen Demeyer.  (Github issue #2904)
+  Patch by Jeroen Demeyer.  (Github issue :issue:`2904`)
 
 * The search order for include files was changed. Previously it was
   ``include_directories``, ``Cython/Includes``, ``sys.path``. Now it is
   ``include_directories``, ``sys.path``, ``Cython/Includes``. This was done to
   allow third-party ``*.pxd`` files to override the ones in Cython.
-  Patch by Matti Picus.  (Github issue #2905)
+  Patch by Matti Picus.  (Github issue :issue:`2905`)
 
 * The command line parser was rewritten and modernised using ``argparse``.
-  Patch by Egor Dranischnikow.  (Github issue #2952, #3001)
+  Patch by Egor Dranischnikow.  (Github issue :issue:`2952`, :issue:`3001`)
 
 * Dotted filenames for qualified module names (``pkg.mod.pyx``) are deprecated.
   Use the normal Python package directory layout instead.
-  (Github issue #2686)
+  (Github issue :issue:`2686`)
 
 * Binary Linux wheels now follow the manylinux2010 standard.
-  Patch by Alexey Stepanov.  (Github issue #3355)
+  Patch by Alexey Stepanov.  (Github issue :issue:`3355`)
 
 * Support for Python 2.6 was removed.
 
+.. _`PEP-560`: https://www.python.org/dev/peps/pep-0560
+.. _`PEP-570`: https://www.python.org/dev/peps/pep-0570
+.. _`PEP-487`: https://www.python.org/dev/peps/pep-0487
+.. _`PEP-590`: https://www.python.org/dev/peps/pep-0590
+.. _`PEP-3131`: https://www.python.org/dev/peps/pep-3131
+.. _`PEP-563`: https://www.python.org/dev/peps/pep-0563
+.. _`PEP-479`: https://www.python.org/dev/peps/pep-0479
 
 0.29.23 (2021-??-??)
 ====================
diff --git a/Cython/Build/Dependencies.py b/Cython/Build/Dependencies.py
index e03046d49..8a268c173 100644
--- a/Cython/Build/Dependencies.py
+++ b/Cython/Build/Dependencies.py
@@ -948,6 +948,11 @@ def cythonize(module_list, exclude=None, nthreads=0, aliases=None, quiet=False,
                      See examples in :ref:`determining_where_to_add_types` or
                      :ref:`primes`.
 
+
+    :param annotate-fullc: If ``True`` will produce a colorized HTML version of
+                           the source which includes entire generated C/C++-code.
+
+
     :param compiler_directives: Allow to set compiler directives in the ``setup.py`` like this:
                                 ``compiler_directives={'embedsignature': True}``.
                                 See :ref:`compiler-directives`.
diff --git a/doc-requirements.txt b/doc-requirements.txt
new file mode 100644
index 000000000..2494b1d37
--- /dev/null
+++ b/doc-requirements.txt
@@ -0,0 +1,2 @@
+sphinx==3.5.3
+sphinx-issues==1.2.0
diff --git a/docs/conf.py b/docs/conf.py
index c20a57574..5ffc995f9 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -44,7 +44,8 @@ extensions = [
     'sphinx.ext.imgmath',
     'sphinx.ext.todo',
     'sphinx.ext.intersphinx',
-    'sphinx.ext.autodoc'
+    'sphinx.ext.autodoc',
+    'sphinx_issues',  # if this is missing, pip install sphinx-issues
     ]
 
 try: import rst2pdf
@@ -135,6 +136,9 @@ intersphinx_mapping = {'python': ('https://docs.python.org/3/', None)}
 # The output image format. The default is 'png'. It should be either 'png' or 'svg'.
 imgmath_image_format = "svg"
 
+# For sphinx-issues
+
+issues_github_path = "cython/cython"
 
 # -- Options for HTML output ---------------------------------------------------
 
diff --git a/docs/examples/README.rst b/docs/examples/README.rst
index e246c96bc..f998f4f33 100644
--- a/docs/examples/README.rst
+++ b/docs/examples/README.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 This example directory is organized like the ``Cython/docs/src/`` directory,
 with one directory per ``.rst`` file. All files in this directory are tested
 in the :file:`runtests.py` with the mode `compile`.
diff --git a/docs/index.rst b/docs/index.rst
index 7dc6ac525..0103d8d9f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,4 +10,6 @@ Also see the `Cython project homepage <https://cython.org/>`_.
    src/quickstart/index
    src/tutorial/index
    src/userguide/index
+   src/reference/index
+   Contributing <CONTRIBUTING>
    src/changes
diff --git a/docs/src/donating.rst b/docs/src/donating.rst
index db9f24c61..3d12a8691 100644
--- a/docs/src/donating.rst
+++ b/docs/src/donating.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 🌷️ Thank you for your interest in supporting Cython! 🌷️
 =========================================================
 
diff --git a/docs/src/reference/directives.rst b/docs/src/reference/directives.rst
index f527536a8..46d7fa9c4 100644
--- a/docs/src/reference/directives.rst
+++ b/docs/src/reference/directives.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Compiler Directives
 ===================
 
diff --git a/docs/src/reference/extension_types.rst b/docs/src/reference/extension_types.rst
index ea26f38a0..3c5cc828d 100644
--- a/docs/src/reference/extension_types.rst
+++ b/docs/src/reference/extension_types.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. highlight:: cython
 
 ***************
diff --git a/docs/src/reference/language_basics.rst b/docs/src/reference/language_basics.rst
index bd8b1e38c..8d7cd0b06 100644
--- a/docs/src/reference/language_basics.rst
+++ b/docs/src/reference/language_basics.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. highlight:: cython
 
 
diff --git a/docs/src/tutorial/external.rst b/docs/src/tutorial/external.rst
index 42b1ed0c2..83ec75375 100644
--- a/docs/src/tutorial/external.rst
+++ b/docs/src/tutorial/external.rst
@@ -30,6 +30,8 @@ your code is being compiled with, you can do this:
 
 .. literalinclude:: ../../examples/tutorial/external/py_version_hex.pyx
 
+.. _libc.math:
+
 Cython also provides declarations for the C math library:
 
 .. literalinclude:: ../../examples/tutorial/external/libc_sin.pyx
diff --git a/docs/src/userguide/extension_types.rst b/docs/src/userguide/extension_types.rst
index f8f7f4f70..e7f95a7ab 100644
--- a/docs/src/userguide/extension_types.rst
+++ b/docs/src/userguide/extension_types.rst
@@ -669,6 +669,8 @@ objects from memory. Clearing is implemented in the ``tp_clear`` slot.
 As we just explained, it is sufficient that one object in the cycle
 implements ``tp_clear``.
 
+.. _trashcan:
+
 Enabling the deallocation trashcan
 ----------------------------------
 
@@ -965,7 +967,8 @@ C inline properties
 Similar to Python property attributes, Cython provides a way to declare C-level
 properties on external extension types.  This is often used to shadow Python
 attributes through faster C level data access, but can also be used to add certain
-functionality to existing types when using them from Cython.
+functionality to existing types when using them from Cython. The declarations
+must use `cdef inline`.
 
 For example, the above ``complex`` type could also be declared like this:
 
diff --git a/docs/src/userguide/glossary.rst b/docs/src/userguide/glossary.rst
index 9a9aab52b..1ccbb4408 100644
--- a/docs/src/userguide/glossary.rst
+++ b/docs/src/userguide/glossary.rst
@@ -1,10 +1,12 @@
 .. glossary::
 
+Glossary
+========
+
    Extension type
       "Extension type" can refer to either a Cython class defined with ``cdef class`` or more generally to any Python type that is ultimately implemented as a native C struct (including the built-in types like `int` or `dict`).
       
-   Dynamic allocation
-   Heap allocation
+   Dynamic allocation or Heap allocation
       A C variable allocated with ``malloc`` (in C) or ``new`` (in C++) is
       `allocated dynamically/heap allocated <https://en.wikipedia.org/wiki/C_dynamic_memory_allocation>`_.
       Its lifetime is until the user deletes it explicitly (with ``free`` in C or ``del`` in C++).
@@ -19,9 +21,9 @@
    Python object
       When using Python, the contents of every variable is a Python object
       (including Cython extension types). Key features of Python objects are that
-      they are passed _by reference_ and that their lifetime is _managed_ automatically
+      they are passed *by reference* and that their lifetime is *managed* automatically
       so that they are destroyed when no more references exist to them.
-      In Cython, they are distinct from C types, which are passed _by value_ and whose
+      In Cython, they are distinct from C types, which are passed *by value* and whose
       lifetime is managed depending on whether they are allocated on the stack or heap.
       To explicitly declare a Python object variable in Cython use ``cdef object abc``.
       Internally in C, they are referred to as ``PyObject*``.
diff --git a/docs/src/userguide/sharing_declarations.rst b/docs/src/userguide/sharing_declarations.rst
index 32cbee924..70e29e2b2 100644
--- a/docs/src/userguide/sharing_declarations.rst
+++ b/docs/src/userguide/sharing_declarations.rst
@@ -227,6 +227,8 @@ Some things to note about this example:
   when you try to use them from a dependent package.
   To prevent this, include ``zip_safe=False`` in the arguments to ``setup()``.
 
+.. _versioning:
+
 Versioning
 ==========