Trac #33763: Refactor src/sage/docs

We deprecate the package `sage.docs` which contains two modules `conf`
and `instancedoc`.

The module `conf` is not one of normal sage modules, but is the Sphinx
configuration for documentation building. Hence we move the module into
`sage_docbuild`.

The module `instancedoc` provides a decorator to add docstrings to
instance objects. This has nothing to do with building documentation.
Hence we move it to `sage.misc`.

This ticket also refactors the code in `sage_docbuild.__init__`. The
"builders" are moved to a new module `sage_docbuild.builders` and the
"main" function is moved into `sage_docbuild.__main__`.

Finally we add some documentation about Sage's documentation system.

----

**To minimize confusion, this ticket should be merged with sage 9.7.beta
as early as possible (before any other tickets touching `conf.py`)**

URL: https://trac.sagemath.org/33763
Reported by: klee
Ticket author(s): Kwankyu Lee
Reviewer(s): Matthias Koeppe

pkgs/sagemath-objects/MANIFEST.in

@@ -62,7 +62,7 @@ include sage/misc/flatten.*             # dep of sage/categories/coxeter_groups.
 
 include sage/misc/lazy_import*.*
 include sage/misc/sageinspect.*          # dep of sage/misc/lazy_import
-graft sage/docs                          # dep of sage/misc/lazy_import
+include sage/misc/instancedoc.*          # dep of sage/misc/lazy_import
 
 include sage/misc/persist.*
 include sage/misc/sage_unittest.*        # dep of sage/misc/persist

src/doc/ca/intro/conf.py

@@ -10,13 +10,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *  # NOQA
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *  # NOQA
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/de/a_tour_of_sage/conf.py

@@ -12,13 +12,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *  # NOQA
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *  # NOQA
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/de/thematische_anleitungen/conf.py

@@ -10,13 +10,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *  # NOQA
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *  # NOQA
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/de/tutorial/conf.py

@@ -10,13 +10,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *  # NOQA
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *  # NOQA
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/en/a_tour_of_sage/conf.py

@@ -10,13 +10,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *  # NOQA
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *  # NOQA
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/en/constructions/conf.py

@@ -10,13 +10,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *  # NOQA
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *  # NOQA
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/en/developer/conf.py

@@ -10,13 +10,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *  # NOQA
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *  # NOQA
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/en/faq/conf.py

@@ -12,13 +12,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/en/installation/conf.py

@@ -10,13 +10,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *  # NOQA
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *  # NOQA
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/en/prep/conf.py

@@ -10,13 +10,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *  # NOQA
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *  # NOQA
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/en/reference/conf.py

@@ -12,13 +12,13 @@
 
 import os
 from sage.env import SAGE_DOC_SRC, SAGE_DOC
-from sage.docs.conf import release, latex_elements, exclude_patterns
-from sage.docs.conf import *
+from sage_docbuild.conf import release, latex_elements, exclude_patterns
+from sage_docbuild.conf import *
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/en/reference/conf_sub.py

@@ -12,13 +12,13 @@
 
 import os
 from sage.env import SAGE_DOC_SRC, SAGE_DOC
-from sage.docs.conf import release, exclude_patterns
-from sage.docs.conf import *
+from sage_docbuild.conf import release, exclude_patterns
+from sage_docbuild.conf import *
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/en/reference/documentation/conf.py

@@ -0,0 +1 @@
+../conf_sub.py

src/doc/en/reference/documentation/index.rst

@@ -0,0 +1,12 @@
+Documentation System
+====================
+
+.. toctree::
+   :maxdepth: 1
+
+   sage_docbuild/__main__
+   sage_docbuild/builders
+   sage_docbuild/build_options
+   sage_docbuild/sphinxbuild
+   sage_docbuild/conf
+   sage_docbuild/utils

src/doc/en/reference/index.rst

@@ -97,7 +97,7 @@ Geometry, Topology, and Homological Algebra
 
 * :doc:`Euclidean Spaces and Vector Calculus <euclidean_spaces/index>`
 * :doc:`Combinatorial and Discrete Geometry <discrete_geometry/index>`
-* :doc:`Cell Complexes, Simplicial Complexes, and 
+* :doc:`Cell Complexes, Simplicial Complexes, and
   Simplicial Sets <topology/index>`
 * :doc:`Manifolds and Differential Geometry <manifolds/index>`
 * :doc:`Hyperbolic Geometry <hyperbolic_geometry/index>`
@@ -157,6 +157,11 @@ Interfaces
 * :doc:`C/C++ Library Interfaces <libs/index>`
 * :doc:`Python Technicalities <cpython/index>`
 
+Documentation System
+--------------------
+
+* :doc:`Documentation System <documentation/index>`
+
 General Information
 ===================
 

src/doc/en/thematic_tutorials/conf.py

@@ -12,13 +12,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/en/thematic_tutorials/explicit_methods_in_number_theory/conf.py

@@ -10,13 +10,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *  # NOQA
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *  # NOQA
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/en/thematic_tutorials/numerical_sage/conf.py

@@ -10,13 +10,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *  # NOQA
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *  # NOQA
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/en/tutorial/conf.py

@@ -10,13 +10,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *  # NOQA
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *  # NOQA
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/en/website/conf.py

@@ -10,13 +10,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *  # NOQA
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *  # NOQA
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/es/a_tour_of_sage/conf.py

@@ -12,13 +12,13 @@
 # All configuration values have a default; values that are commented
 # out serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/es/tutorial/conf.py

@@ -10,13 +10,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release
-from sage.docs.conf import *
+from sage_docbuild.conf import release
+from sage_docbuild.conf import *
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path
 

src/doc/fr/a_tour_of_sage/conf.py

@@ -10,13 +10,13 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-from sage.docs.conf import release, latex_elements
-from sage.docs.conf import *  # NOQA
+from sage_docbuild.conf import release, latex_elements
+from sage_docbuild.conf import *  # NOQA
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
 # builtin static files, so a file named "default.css" will overwrite the
-# builtin "default.css". html_common_static_path imported from sage.docs.conf
+# builtin "default.css". html_common_static_path imported from sage_docbuild.conf
 # contains common paths.
 html_static_path = [] + html_common_static_path