Fix documentation links (#1048)

* fix warnings, make sphinx fail on warnings

* fix a few links

* fix a bunch of links

* fix more links

* fix all remaining links

* and finally add the link checker

* debug workflow

* more debug

* undo debug

* Add to changelog

* fix new warning

* clean up more errors

* Fix link after rebase

* Apply suggestions from code review

Co-authored-by: PGijsbers <p.gijsbers@tue.nl>

Co-authored-by: PGijsbers <p.gijsbers@tue.nl>

Author: mfeurer

.github/workflows/docs.yaml

@@ -17,6 +17,10 @@ jobs:
       run: |
         cd doc
         make html
+    - name: Check links
+      run: |
+        cd doc
+        make linkcheck
     - name: Pull latest gh-pages
       if: (contains(github.ref, 'develop') || contains(github.ref, 'master')) && github.event_name == 'push'
       run: |

doc/_templates/class.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 :mod:`{{module}}`.{{objname}}
 {{ underline }}==============
 

doc/api.rst

@@ -2,64 +2,33 @@
 
 .. _api:
 
-APIs
-****
+API
+***
 
-Top-level Classes
------------------
-.. currentmodule:: openml
-
-.. autosummary::
-   :toctree: generated/
-   :template: class.rst
-
-   OpenMLBenchmarkSuite
-   OpenMLClassificationTask
-   OpenMLClusteringTask
-   OpenMLDataFeature
-   OpenMLDataset
-   OpenMLEvaluation
-   OpenMLFlow
-   OpenMLLearningCurveTask
-   OpenMLParameter
-   OpenMLRegressionTask
-   OpenMLRun
-   OpenMLSetup
-   OpenMLSplit
-   OpenMLStudy
-   OpenMLSupervisedTask
-   OpenMLTask
+Modules
+=======
 
-.. _api_extensions:
+:mod:`openml.datasets`
+----------------------
+.. automodule:: openml.datasets
+    :no-members:
+    :no-inherited-members:
 
-Extensions
-----------
+Dataset Classes
+~~~~~~~~~~~~~~~
 
-.. currentmodule:: openml.extensions
+.. currentmodule:: openml.datasets
 
 .. autosummary::
    :toctree: generated/
    :template: class.rst
 
-   Extension
-   sklearn.SklearnExtension
-
-.. currentmodule:: openml.extensions
-
-.. autosummary::
-   :toctree: generated/
-   :template: function.rst
-
-    get_extension_by_flow
-    get_extension_by_model
-    register_extension
-
+   OpenMLDataFeature
+   OpenMLDataset
 
-Modules
--------
+Dataset Functions
+~~~~~~~~~~~~~~~~~
 
-:mod:`openml.datasets`: Dataset Functions
------------------------------------------
 .. currentmodule:: openml.datasets
 
 .. autosummary::
@@ -77,20 +46,56 @@ Modules
     edit_dataset
     fork_dataset
 
-:mod:`openml.evaluations`: Evaluation Functions
------------------------------------------------
+:mod:`openml.evaluations`
+-------------------------
+.. automodule:: openml.evaluations
+    :no-members:
+    :no-inherited-members:
+
+Evaluations Classes
+~~~~~~~~~~~~~~~~~~~
+
+.. currentmodule:: openml.evaluations
+
+.. autosummary::
+   :toctree: generated/
+   :template: class.rst
+
+    OpenMLEvaluation
+
+Evaluations Functions
+~~~~~~~~~~~~~~~~~~~~~
+
 .. currentmodule:: openml.evaluations
 
 .. autosummary::
    :toctree: generated/
    :template: function.rst
 
-    list_evaluations
-    list_evaluation_measures
-    list_evaluations_setups
+   list_evaluations
+   list_evaluation_measures
+   list_evaluations_setups
 
 :mod:`openml.flows`: Flow Functions
 -----------------------------------
+.. automodule:: openml.flows
+    :no-members:
+    :no-inherited-members:
+
+Flow Classes
+~~~~~~~~~~~~
+
+.. currentmodule:: openml.flows
+
+.. autosummary::
+   :toctree: generated/
+   :template: class.rst
+
+    OpenMLFlow
+
+Flow Functions
+~~~~~~~~~~~~~~
+
 .. currentmodule:: openml.flows
 
 .. autosummary::
@@ -104,6 +109,24 @@ Modules
 
 :mod:`openml.runs`: Run Functions
 ----------------------------------
+.. automodule:: openml.runs
+    :no-members:
+    :no-inherited-members:
+
+Run Classes
+~~~~~~~~~~~
+
+.. currentmodule:: openml.runs
+
+.. autosummary::
+   :toctree: generated/
+   :template: class.rst
+
+    OpenMLRun
+
+Run Functions
+~~~~~~~~~~~~~
+
 .. currentmodule:: openml.runs
 
 .. autosummary::
@@ -122,6 +145,25 @@ Modules
 
 :mod:`openml.setups`: Setup Functions
 -------------------------------------
+.. automodule:: openml.setups
+    :no-members:
+    :no-inherited-members:
+
+Setup Classes
+~~~~~~~~~~~~~
+
+.. currentmodule:: openml.setups
+
+.. autosummary::
+   :toctree: generated/
+   :template: class.rst
+
+   OpenMLParameter
+   OpenMLSetup
+
+Setup Functions
+~~~~~~~~~~~~~~~
+
 .. currentmodule:: openml.setups
 
 .. autosummary::
@@ -135,6 +177,25 @@ Modules
 
 :mod:`openml.study`: Study Functions
 ------------------------------------
+.. automodule:: openml.study
+    :no-members:
+    :no-inherited-members:
+
+Study Classes
+~~~~~~~~~~~~~
+
+.. currentmodule:: openml.study
+
+.. autosummary::
+   :toctree: generated/
+   :template: class.rst
+
+   OpenMLBenchmarkSuite
+   OpenMLStudy
+
+Study Functions
+~~~~~~~~~~~~~~~
+
 .. currentmodule:: openml.study
 
 .. autosummary::
@@ -158,6 +219,31 @@ Modules
 
 :mod:`openml.tasks`: Task Functions
 -----------------------------------
+.. automodule:: openml.tasks
+    :no-members:
+    :no-inherited-members:
+
+Task Classes
+~~~~~~~~~~~~
+
+.. currentmodule:: openml.tasks
+
+.. autosummary::
+   :toctree: generated/
+   :template: class.rst
+
+   OpenMLClassificationTask
+   OpenMLClusteringTask
+   OpenMLLearningCurveTask
+   OpenMLRegressionTask
+   OpenMLSplit
+   OpenMLSupervisedTask
+   OpenMLTask
+   TaskType
+
+Task Functions
+~~~~~~~~~~~~~~
+
 .. currentmodule:: openml.tasks
 
 .. autosummary::
@@ -168,3 +254,38 @@ Modules
     get_task
     get_tasks
     list_tasks
+
+.. _api_extensions:
+
+Extensions
+==========
+
+.. automodule:: openml.extensions
+    :no-members:
+    :no-inherited-members:
+
+Extension Classes
+-----------------
+
+.. currentmodule:: openml.extensions
+
+.. autosummary::
+   :toctree: generated/
+   :template: class.rst
+
+   Extension
+   sklearn.SklearnExtension
+
+Extension Functions
+-------------------
+
+.. currentmodule:: openml.extensions
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
+    get_extension_by_flow
+    get_extension_by_model
+    register_extension
+

doc/conf.py

@@ -114,6 +114,11 @@
 # If true, keep warnings as "system message" paragraphs in the built documents.
 # keep_warnings = False
 
+# Complain about all broken internal links - broken external links can be
+# found with `make linkcheck`
+#
+# currently disabled because without intersphinx we cannot link to numpy.ndarray
+# nitpicky = True
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -344,3 +349,4 @@
 
 def setup(app):
     app.add_css_file("codehighlightstyle.css")
+    app.warningiserror = True

doc/contributing.rst

@@ -19,7 +19,7 @@ In particular, a few ways to contribute to openml-python are:
    For more information, see the :ref:`extensions` below.
 
  * Bug reports. If something doesn't work for you or is cumbersome, please open a new issue to let
-   us know about the problem. See `this section <https://github.com/openml/openml-python/blob/develop/CONTRIBUTING.md#reporting-bugs>`_.
+   us know about the problem. See `this section <https://github.com/openml/openml-python/blob/master/CONTRIBUTING.md#user-content-reporting-bugs>`_.
 
  * `Cite OpenML <https://www.openml.org/cite>`_ if you use it in a scientific publication.
 
@@ -38,10 +38,10 @@ Content of the Library
 To leverage support from the community and to tap in the potential of OpenML, interfacing
 with popular machine learning libraries is essential. However, the OpenML-Python team does
 not have the capacity to develop and maintain such interfaces on its own. For this, we
-have built an extension interface to allows others to contribute back. Building a suitable 
+have built an extension interface to allows others to contribute back. Building a suitable
 extension for therefore requires an understanding of the current OpenML-Python support.
 
-`This example <examples/20_basic/simple_flows_and_runs_tutorial.html>`_
+The :ref:`sphx_glr_examples_20_basic_simple_flows_and_runs_tutorial.py` tutorial
 shows how scikit-learn currently works with OpenML-Python as an extension. The *sklearn*
 extension packaged with the `openml-python <https://github.com/openml/openml-python>`_
 repository can be used as a template/benchmark to build the new extension.
@@ -50,7 +50,7 @@ repository can be used as a template/benchmark to build the new extension.
 API
 +++
 * The extension scripts must import the `openml` package and be able to interface with
-  any function from the OpenML-Python `API <api.html>`_.
+  any function from the OpenML-Python :ref:`api`.
 * The extension has to be defined as a Python class and must inherit from
   :class:`openml.extensions.Extension`.
 * This class needs to have all the functions from `class Extension` overloaded as required.
@@ -61,7 +61,7 @@ API
 
 Interfacing with OpenML-Python
 ++++++++++++++++++++++++++++++
-Once the new extension class has been defined, the openml-python module to 
+Once the new extension class has been defined, the openml-python module to
 :meth:`openml.extensions.register_extension` must be called to allow OpenML-Python to
 interface the new extension.
 
@@ -73,8 +73,8 @@ Each extension created should be a stand-alone repository, compatible with the
 `OpenML-Python repository <https://github.com/openml/openml-python>`_.
 The extension repository should work off-the-shelf with *OpenML-Python* installed.
 
-Create a `public Github repo <https://help.github.com/en/articles/create-a-repo>`_ with
-the following directory structure:
+Create a `public Github repo <https://docs.github.com/en/github/getting-started-with-github/create-a-repo>`_
+with the following directory structure:
 
 ::