Skip to content

Commit 3d83936

Browse files
mfeurerPGijsbers
mfeurer
and
PGijsbers
committed
Fix documentation links (openml#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>
1 parent 68311de commit 3d83936

32 files changed

Lines changed: 293 additions & 158 deletions

‎.github/workflows/docs.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,10 @@ jobs:
1717
run: |
1818
cd doc
1919
make html
20+
- name: Check links
21+
run: |
22+
cd doc
23+
make linkcheck
2024
- name: Pull latest gh-pages
2125
if: (contains(github.ref, 'develop') || contains(github.ref, 'master')) && github.event_name == 'push'
2226
run: |

‎doc/_templates/class.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
:orphan:
2+
13
:mod:`{{module}}`.{{objname}}
24
{{ underline }}==============
35

‎doc/api.rst‎

Lines changed: 173 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -2,64 +2,33 @@
22

33
.. _api:
44

5-
APIs
6-
****
5+
API
6+
***
77

8-
Top-level Classes
9-
-----------------
10-
.. currentmodule:: openml
11-
12-
.. autosummary::
13-
:toctree: generated/
14-
:template: class.rst
15-
16-
OpenMLBenchmarkSuite
17-
OpenMLClassificationTask
18-
OpenMLClusteringTask
19-
OpenMLDataFeature
20-
OpenMLDataset
21-
OpenMLEvaluation
22-
OpenMLFlow
23-
OpenMLLearningCurveTask
24-
OpenMLParameter
25-
OpenMLRegressionTask
26-
OpenMLRun
27-
OpenMLSetup
28-
OpenMLSplit
29-
OpenMLStudy
30-
OpenMLSupervisedTask
31-
OpenMLTask
8+
Modules
9+
=======
3210

33-
.. _api_extensions:
11+
:mod:`openml.datasets`
12+
----------------------
13+
.. automodule:: openml.datasets
14+
:no-members:
15+
:no-inherited-members:
3416

35-
Extensions
36-
----------
17+
Dataset Classes
18+
~~~~~~~~~~~~~~~
3719

38-
.. currentmodule:: openml.extensions
20+
.. currentmodule:: openml.datasets
3921

4022
.. autosummary::
4123
:toctree: generated/
4224
:template: class.rst
4325

44-
Extension
45-
sklearn.SklearnExtension
46-
47-
.. currentmodule:: openml.extensions
48-
49-
.. autosummary::
50-
:toctree: generated/
51-
:template: function.rst
52-
53-
get_extension_by_flow
54-
get_extension_by_model
55-
register_extension
56-
26+
OpenMLDataFeature
27+
OpenMLDataset
5728

58-
Modules
59-
-------
29+
Dataset Functions
30+
~~~~~~~~~~~~~~~~~
6031

61-
:mod:`openml.datasets`: Dataset Functions
62-
-----------------------------------------
6332
.. currentmodule:: openml.datasets
6433

6534
.. autosummary::
@@ -78,20 +47,56 @@ Modules
7847
edit_dataset
7948
fork_dataset
8049

81-
:mod:`openml.evaluations`: Evaluation Functions
82-
-----------------------------------------------
50+
:mod:`openml.evaluations`
51+
-------------------------
52+
.. automodule:: openml.evaluations
53+
:no-members:
54+
:no-inherited-members:
55+
56+
Evaluations Classes
57+
~~~~~~~~~~~~~~~~~~~
58+
59+
.. currentmodule:: openml.evaluations
60+
61+
.. autosummary::
62+
:toctree: generated/
63+
:template: class.rst
64+
65+
OpenMLEvaluation
66+
67+
Evaluations Functions
68+
~~~~~~~~~~~~~~~~~~~~~
69+
8370
.. currentmodule:: openml.evaluations
8471

8572
.. autosummary::
8673
:toctree: generated/
8774
:template: function.rst
8875

89-
list_evaluations
90-
list_evaluation_measures
91-
list_evaluations_setups
76+
list_evaluations
77+
list_evaluation_measures
78+
list_evaluations_setups
9279

9380
:mod:`openml.flows`: Flow Functions
9481
-----------------------------------
82+
.. automodule:: openml.flows
83+
:no-members:
84+
:no-inherited-members:
85+
86+
Flow Classes
87+
~~~~~~~~~~~~
88+
89+
.. currentmodule:: openml.flows
90+
91+
.. autosummary::
92+
:toctree: generated/
93+
:template: class.rst
94+
95+
OpenMLFlow
96+
97+
Flow Functions
98+
~~~~~~~~~~~~~~
99+
95100
.. currentmodule:: openml.flows
96101

97102
.. autosummary::
@@ -106,6 +111,24 @@ Modules
106111

107112
:mod:`openml.runs`: Run Functions
108113
----------------------------------
114+
.. automodule:: openml.runs
115+
:no-members:
116+
:no-inherited-members:
117+
118+
Run Classes
119+
~~~~~~~~~~~
120+
121+
.. currentmodule:: openml.runs
122+
123+
.. autosummary::
124+
:toctree: generated/
125+
:template: class.rst
126+
127+
OpenMLRun
128+
129+
Run Functions
130+
~~~~~~~~~~~~~
131+
109132
.. currentmodule:: openml.runs
110133

111134
.. autosummary::
@@ -125,6 +148,25 @@ Modules
125148

126149
:mod:`openml.setups`: Setup Functions
127150
-------------------------------------
151+
.. automodule:: openml.setups
152+
:no-members:
153+
:no-inherited-members:
154+
155+
Setup Classes
156+
~~~~~~~~~~~~~
157+
158+
.. currentmodule:: openml.setups
159+
160+
.. autosummary::
161+
:toctree: generated/
162+
:template: class.rst
163+
164+
OpenMLParameter
165+
OpenMLSetup
166+
167+
Setup Functions
168+
~~~~~~~~~~~~~~~
169+
128170
.. currentmodule:: openml.setups
129171

130172
.. autosummary::
@@ -138,6 +180,25 @@ Modules
138180

139181
:mod:`openml.study`: Study Functions
140182
------------------------------------
183+
.. automodule:: openml.study
184+
:no-members:
185+
:no-inherited-members:
186+
187+
Study Classes
188+
~~~~~~~~~~~~~
189+
190+
.. currentmodule:: openml.study
191+
192+
.. autosummary::
193+
:toctree: generated/
194+
:template: class.rst
195+
196+
OpenMLBenchmarkSuite
197+
OpenMLStudy
198+
199+
Study Functions
200+
~~~~~~~~~~~~~~~
201+
141202
.. currentmodule:: openml.study
142203

143204
.. autosummary::
@@ -161,6 +222,31 @@ Modules
161222

162223
:mod:`openml.tasks`: Task Functions
163224
-----------------------------------
225+
.. automodule:: openml.tasks
226+
:no-members:
227+
:no-inherited-members:
228+
229+
Task Classes
230+
~~~~~~~~~~~~
231+
232+
.. currentmodule:: openml.tasks
233+
234+
.. autosummary::
235+
:toctree: generated/
236+
:template: class.rst
237+
238+
OpenMLClassificationTask
239+
OpenMLClusteringTask
240+
OpenMLLearningCurveTask
241+
OpenMLRegressionTask
242+
OpenMLSplit
243+
OpenMLSupervisedTask
244+
OpenMLTask
245+
TaskType
246+
247+
Task Functions
248+
~~~~~~~~~~~~~~
249+
164250
.. currentmodule:: openml.tasks
165251

166252
.. autosummary::
@@ -172,3 +258,38 @@ Modules
172258
get_task
173259
get_tasks
174260
list_tasks
261+
262+
.. _api_extensions:
263+
264+
Extensions
265+
==========
266+
267+
.. automodule:: openml.extensions
268+
:no-members:
269+
:no-inherited-members:
270+
271+
Extension Classes
272+
-----------------
273+
274+
.. currentmodule:: openml.extensions
275+
276+
.. autosummary::
277+
:toctree: generated/
278+
:template: class.rst
279+
280+
Extension
281+
sklearn.SklearnExtension
282+
283+
Extension Functions
284+
-------------------
285+
286+
.. currentmodule:: openml.extensions
287+
288+
.. autosummary::
289+
:toctree: generated/
290+
:template: function.rst
291+
292+
get_extension_by_flow
293+
get_extension_by_model
294+
register_extension
295+

‎doc/conf.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,11 @@
114114
# If true, keep warnings as "system message" paragraphs in the built documents.
115115
# keep_warnings = False
116116

117+
# Complain about all broken internal links - broken external links can be
118+
# found with `make linkcheck`
119+
#
120+
# currently disabled because without intersphinx we cannot link to numpy.ndarray
121+
# nitpicky = True
117122

118123
# -- Options for HTML output ----------------------------------------------
119124

@@ -344,3 +349,4 @@
344349

345350
def setup(app):
346351
app.add_css_file("codehighlightstyle.css")
352+
app.warningiserror = True

‎doc/contributing.rst‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ In particular, a few ways to contribute to openml-python are:
1919
For more information, see the :ref:`extensions` below.
2020

2121
* Bug reports. If something doesn't work for you or is cumbersome, please open a new issue to let
22-
us know about the problem. See `this section <https://github.com/openml/openml-python/blob/develop/CONTRIBUTING.md#reporting-bugs>`_.
22+
us know about the problem. See `this section <https://github.com/openml/openml-python/blob/master/CONTRIBUTING.md#user-content-reporting-bugs>`_.
2323

2424
* `Cite OpenML <https://www.openml.org/cite>`_ if you use it in a scientific publication.
2525

@@ -38,10 +38,10 @@ Content of the Library
3838
To leverage support from the community and to tap in the potential of OpenML, interfacing
3939
with popular machine learning libraries is essential. However, the OpenML-Python team does
4040
not have the capacity to develop and maintain such interfaces on its own. For this, we
41-
have built an extension interface to allows others to contribute back. Building a suitable
41+
have built an extension interface to allows others to contribute back. Building a suitable
4242
extension for therefore requires an understanding of the current OpenML-Python support.
4343

44-
`This example <examples/20_basic/simple_flows_and_runs_tutorial.html>`_
44+
The :ref:`sphx_glr_examples_20_basic_simple_flows_and_runs_tutorial.py` tutorial
4545
shows how scikit-learn currently works with OpenML-Python as an extension. The *sklearn*
4646
extension packaged with the `openml-python <https://github.com/openml/openml-python>`_
4747
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.
5050
API
5151
+++
5252
* The extension scripts must import the `openml` package and be able to interface with
53-
any function from the OpenML-Python `API <api.html>`_.
53+
any function from the OpenML-Python :ref:`api`.
5454
* The extension has to be defined as a Python class and must inherit from
5555
:class:`openml.extensions.Extension`.
5656
* This class needs to have all the functions from `class Extension` overloaded as required.
@@ -61,7 +61,7 @@ API
6161

6262
Interfacing with OpenML-Python
6363
++++++++++++++++++++++++++++++
64-
Once the new extension class has been defined, the openml-python module to
64+
Once the new extension class has been defined, the openml-python module to
6565
:meth:`openml.extensions.register_extension` must be called to allow OpenML-Python to
6666
interface the new extension.
6767

@@ -73,8 +73,8 @@ Each extension created should be a stand-alone repository, compatible with the
7373
`OpenML-Python repository <https://github.com/openml/openml-python>`_.
7474
The extension repository should work off-the-shelf with *OpenML-Python* installed.
7575

76-
Create a `public Github repo <https://help.github.com/en/articles/create-a-repo>`_ with
77-
the following directory structure:
76+
Create a `public Github repo <https://docs.github.com/en/github/getting-started-with-github/create-a-repo>`_
77+
with the following directory structure:
7878

7979
::
8080

0 commit comments

Comments
 (0)