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

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`.

doc-requirements.txt

+sphinx==3.5.3
+sphinx-issues==1.2.0

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 ---------------------------------------------------
 

docs/examples/README.rst

+: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`.

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

docs/src/donating.rst

+:orphan:
+
 🌷️ Thank you for your interest in supporting Cython! 🌷️
 =========================================================
 

docs/src/reference/directives.rst

+:orphan:
+
 Compiler Directives
 ===================
 

docs/src/reference/extension_types.rst

+:orphan:
+
 .. highlight:: cython
 
 ***************

docs/src/reference/language_basics.rst

+:orphan:
+
 .. highlight:: cython
 
 

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

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:
 

docs/src/userguide/glossary.rst

 .. 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*``.

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
 ==========