diff --git a/doc/about.rst b/doc/about.rst index f4631b29ef099..5861cc566d91d 100644 --- a/doc/about.rst +++ b/doc/about.rst @@ -85,8 +85,8 @@ citations to the following paper: If you want to cite scikit-learn for its API or design, you may also want to consider the following paper: - `API design for machine learning software: experiences from the scikit-learn - project `_, Buitinck *et al.*, 2013. + :arxiv:`API design for machine learning software: experiences from the scikit-learn + project <1309.0238>`, Buitinck *et al.*, 2013. Bibtex entry:: diff --git a/doc/conf.py b/doc/conf.py index 659a5d70fa32b..97741dfd8388a 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -48,6 +48,7 @@ "add_toctree_functions", "sphinx-prompt", "sphinxext.opengraph", + "doi_role", ] # Support for `plot::` directives in sphinx 3.2 requires matplotlib 3.1.0 or newer diff --git a/doc/modules/clustering.rst b/doc/modules/clustering.rst index 65f33fe1fbebb..f3da4d7fa432a 100644 --- a/doc/modules/clustering.rst +++ b/doc/modules/clustering.rst @@ -544,9 +544,9 @@ graph, and SpectralClustering is initialized with `affinity='precomputed'`:: `_ Andrew Y. Ng, Michael I. Jordan, Yair Weiss, 2001 - * `"Preconditioned Spectral Clustering for Stochastic + * :arxiv:`"Preconditioned Spectral Clustering for Stochastic Block Partition Streaming Graph Challenge" - `_ + <1309.0238>` David Zhuzhunashvili, Andrew Knyazev .. _hierarchical_clustering: @@ -1702,10 +1702,9 @@ cluster analysis. .. topic:: References - * Peter J. Rousseeuw (1987). "Silhouettes: a Graphical Aid to the - Interpretation and Validation of Cluster Analysis". Computational - and Applied Mathematics 20: 53–65. - `doi:10.1016/0377-0427(87)90125-7 `_. + * Peter J. Rousseeuw (1987). :doi:`"Silhouettes: a Graphical Aid to the + Interpretation and Validation of Cluster Analysis"<10.1016/0377-0427(87)90125-7>` + . Computational and Applied Mathematics 20: 53–65. Advantages @@ -1804,8 +1803,7 @@ number of points in cluster :math:`q`. * Caliński, T., & Harabasz, J. (1974). `"A Dendrite Method for Cluster Analysis" `_. - Communications in Statistics-theory and Methods 3: 1-27. - `doi:10.1080/03610927408827101 `_. + :doi:`Communications in Statistics-theory and Methods 3: 1-27 <10.1080/03610927408827101>`. .. _davies-bouldin_index: @@ -1880,15 +1878,13 @@ Then the Davies-Bouldin index is defined as: .. topic:: References * Davies, David L.; Bouldin, Donald W. (1979). - "A Cluster Separation Measure" + :doi:`"A Cluster Separation Measure" <10.1109/TPAMI.1979.4766909>` IEEE Transactions on Pattern Analysis and Machine Intelligence. PAMI-1 (2): 224-227. - `doi:10.1109/TPAMI.1979.4766909 `_. * Halkidi, Maria; Batistakis, Yannis; Vazirgiannis, Michalis (2001). - "On Clustering Validation Techniques" + :doi:`"On Clustering Validation Techniques" <10.1023/A:1012801612483>` Journal of Intelligent Information Systems, 17(2-3), 107-145. - `doi:10.1023/A:1012801612483 `_. * `Wikipedia entry for Davies-Bouldin index `_. diff --git a/doc/modules/decomposition.rst b/doc/modules/decomposition.rst index a76810bbead6f..54ed20cc36be4 100644 --- a/doc/modules/decomposition.rst +++ b/doc/modules/decomposition.rst @@ -167,9 +167,9 @@ Note: the implementation of ``inverse_transform`` in :class:`PCA` with .. topic:: References: * Algorithm 4.3 in - `"Finding structure with randomness: Stochastic algorithms for + :arxiv:`"Finding structure with randomness: Stochastic algorithms for constructing approximate matrix decompositions" - `_ + <0909.4061>` Halko, et al., 2009 * `"An implementation of a randomized algorithm for principal component @@ -341,13 +341,13 @@ components is less than 10 (strict) and the number of samples is more than 200 * *randomized* solver: - - Algorithm 4.3 in - `"Finding structure with randomness: Stochastic algorithms for + * Algorithm 4.3 in + :arxiv:`"Finding structure with randomness: Stochastic algorithms for constructing approximate matrix decompositions" - `_ + <0909.4061>` Halko, et al., 2009 - - `"An implementation of a randomized algorithm for principal component + * `"An implementation of a randomized algorithm for principal component analysis" `_ A. Szlam et al. 2014 diff --git a/doc/modules/ensemble.rst b/doc/modules/ensemble.rst index 91fc892f79d0a..98ad4cc68b75a 100644 --- a/doc/modules/ensemble.rst +++ b/doc/modules/ensemble.rst @@ -1210,8 +1210,8 @@ Finally, many parts of the implementation of `_ .. [R2007] G. Ridgeway, "Generalized Boosted Models: A guide to the gbm package", 2007 - .. [XGBoost] Tianqi Chen, Carlos Guestrin, `"XGBoost: A Scalable Tree - Boosting System" `_ + .. [XGBoost] Tianqi Chen, Carlos Guestrin, :arxiv:`"XGBoost: A Scalable Tree + Boosting System" <1603.02754>` .. [LightGBM] Ke et. al. `"LightGBM: A Highly Efficient Gradient BoostingDecision Tree" `_ diff --git a/doc/modules/grid_search.rst b/doc/modules/grid_search.rst index 331607c86e657..19910d5a16da3 100644 --- a/doc/modules/grid_search.rst +++ b/doc/modules/grid_search.rst @@ -538,9 +538,8 @@ since it has reached the last iteration (3) with the highest score: Optimization `_, in proc. of Machine Learning Research, 2016. .. [2] L. Li, K. Jamieson, G. DeSalvo, A. Rostamizadeh, A. Talwalkar, - `Hyperband: A Novel Bandit-Based Approach to Hyperparameter Optimization - `_, in Machine Learning Research - 18, 2018. + :arxiv:`Hyperband: A Novel Bandit-Based Approach to Hyperparameter Optimization + <1603.06560>`, in Machine Learning Research 18, 2018. .. _grid_search_tips: diff --git a/doc/modules/kernel_approximation.rst b/doc/modules/kernel_approximation.rst index b7de01e308519..b82da8e43582a 100644 --- a/doc/modules/kernel_approximation.rst +++ b/doc/modules/kernel_approximation.rst @@ -246,8 +246,8 @@ or store training examples. .. [VVZ2010] `"Generalized RBF feature maps for Efficient Detection" `_ Vempati, S. and Vedaldi, A. and Zisserman, A. and Jawahar, CV - 2010 - .. [PP2013] `"Fast and scalable polynomial kernels via explicit feature maps" - `_ + .. [PP2013] :doi:`"Fast and scalable polynomial kernels via explicit feature maps" + <10.1145/2487575.2487591>` Pham, N., & Pagh, R. - 2013 .. [CCF2002] `"Finding frequent items in data streams" `_ diff --git a/doc/modules/linear_model.rst b/doc/modules/linear_model.rst index fcc8ed5437ad4..18e1bf468dc62 100644 --- a/doc/modules/linear_model.rst +++ b/doc/modules/linear_model.rst @@ -934,7 +934,9 @@ to warm-starting (see :term:`Glossary `). .. [6] Mark Schmidt, Nicolas Le Roux, and Francis Bach: `Minimizing Finite Sums with the Stochastic Average Gradient. `_ - .. [7] Aaron Defazio, Francis Bach, Simon Lacoste-Julien: `SAGA: A Fast Incremental Gradient Method With Support for Non-Strongly Convex Composite Objectives. `_ + .. [7] Aaron Defazio, Francis Bach, Simon Lacoste-Julien: + :arxiv:`SAGA: A Fast Incremental Gradient Method With Support for + Non-Strongly Convex Composite Objectives. <1407.0202>` .. [8] https://en.wikipedia.org/wiki/Broyden%E2%80%93Fletcher%E2%80%93Goldfarb%E2%80%93Shanno_algorithm @@ -1492,12 +1494,12 @@ problem. The current implementation is based on `_ Econometrica: journal of the Econometric Society, 33-50. - * Portnoy, S., & Koenker, R. (1997). The Gaussian hare and the Laplacian + * Portnoy, S., & Koenker, R. (1997). :doi:`The Gaussian hare and the Laplacian tortoise: computability of squared-error versus absolute-error estimators. - Statistical Science, 12, 279-300. https://doi.org/10.1214/ss/1030037960 + Statistical Science, 12, 279-300 <10.1214/ss/1030037960>`. - * Koenker, R. (2005). Quantile Regression. - Cambridge University Press. https://doi.org/10.1017/CBO9780511754098 + * Koenker, R. (2005). :doi:`Quantile Regression <10.1017/CBO9780511754098>`. + Cambridge University Press. .. _polynomial_regression: diff --git a/doc/modules/model_evaluation.rst b/doc/modules/model_evaluation.rst index 3dd7313bb9b59..730b094581276 100644 --- a/doc/modules/model_evaluation.rst +++ b/doc/modules/model_evaluation.rst @@ -563,8 +563,9 @@ or *informedness*. Machine Learning for Predictive Data Analytics: Algorithms, Worked Examples, and Case Studies `_, 2015. - .. [Urbanowicz2015] Urbanowicz R.J., Moore, J.H. `ExSTraCS 2.0: description and evaluation of a scalable learning - classifier system `_, Evol. Intel. (2015) 8: 89. + .. [Urbanowicz2015] Urbanowicz R.J., Moore, J.H. :doi:`ExSTraCS 2.0: description + and evaluation of a scalable learning classifier + system <10.1007/s12065-015-0128-8>`, Evol. Intel. (2015) 8: 89. .. _cohen_kappa: diff --git a/doc/modules/neural_networks_supervised.rst b/doc/modules/neural_networks_supervised.rst index b9f4e17c6a575..b8bcf4c70a1dc 100644 --- a/doc/modules/neural_networks_supervised.rst +++ b/doc/modules/neural_networks_supervised.rst @@ -184,7 +184,7 @@ Algorithms MLP trains using `Stochastic Gradient Descent `_, -`Adam `_, or +:arxiv:`Adam <1412.6980>`, or `L-BFGS `__. Stochastic Gradient Descent (SGD) updates parameters using the gradient of the loss function with respect to a parameter that needs adaptation, i.e. diff --git a/doc/modules/partial_dependence.rst b/doc/modules/partial_dependence.rst index 8fc97f34e7490..ba99be02c8e4a 100644 --- a/doc/modules/partial_dependence.rst +++ b/doc/modules/partial_dependence.rst @@ -262,8 +262,8 @@ estimators that support it, and 'brute' is used for the rest. C. Molnar, `Interpretable Machine Learning `_, Section 5.1, 2019. - A. Goldstein, A. Kapelner, J. Bleich, and E. Pitkin, `Peeking Inside the + A. Goldstein, A. Kapelner, J. Bleich, and E. Pitkin, :arxiv:`Peeking Inside the Black Box: Visualizing Statistical Learning With Plots of Individual - Conditional Expectation `_, + Conditional Expectation <1309.6392>`, Journal of Computational and Graphical Statistics, 24(1): 44-65, Springer, 2015. diff --git a/doc/modules/permutation_importance.rst b/doc/modules/permutation_importance.rst index 833c9fb9a696e..477a5cf3fdbbc 100644 --- a/doc/modules/permutation_importance.rst +++ b/doc/modules/permutation_importance.rst @@ -184,5 +184,5 @@ example: .. topic:: References: - .. [1] L. Breiman, "Random Forests", Machine Learning, 45(1), 5-32, - 2001. https://doi.org/10.1023/A:1010933404324 + .. [1] L. Breiman, :doi:`"Random Forests" <10.1023/A:1010933404324>`, + Machine Learning, 45(1), 5-32, 2001. diff --git a/doc/modules/preprocessing.rst b/doc/modules/preprocessing.rst index bd506b0151536..035f2b90203ca 100644 --- a/doc/modules/preprocessing.rst +++ b/doc/modules/preprocessing.rst @@ -977,14 +977,12 @@ Interestingly, a :class:`SplineTransformer` of ``degree=0`` is the same as .. topic:: References: - * Eilers, P., & Marx, B. (1996). Flexible Smoothing with B-splines and - Penalties. Statist. Sci. 11 (1996), no. 2, 89--121. - `doi:10.1214/ss/1038425655 `_ - - * Perperoglou, A., Sauerbrei, W., Abrahamowicz, M. et al. A review of - spline function procedures in R. BMC Med Res Methodol 19, 46 (2019). - `doi:10.1186/s12874-019-0666-3 - `_ + * Eilers, P., & Marx, B. (1996). :doi:`Flexible Smoothing with B-splines and + Penalties <10.1214/ss/1038425655>`. Statist. Sci. 11 (1996), no. 2, 89--121. + + * Perperoglou, A., Sauerbrei, W., Abrahamowicz, M. et al. :doi:`A review of + spline function procedures in R <10.1186/s12874-019-0666-3>`. + BMC Med Res Methodol 19, 46 (2019). .. _function_transformer: diff --git a/doc/sphinxext/doi_role.py b/doc/sphinxext/doi_role.py new file mode 100644 index 0000000000000..f851a12ec69ea --- /dev/null +++ b/doc/sphinxext/doi_role.py @@ -0,0 +1,49 @@ +# -*- coding: utf-8 -*- +""" + doilinks + ~~~~~~~~ + Extension to add links to DOIs. With this extension you can use e.g. + :doi:`10.1016/S0022-2836(05)80360-2` in your documents. This will + create a link to a DOI resolver + (``https://doi.org/10.1016/S0022-2836(05)80360-2``). + The link caption will be the raw DOI. + You can also give an explicit caption, e.g. + :doi:`Basic local alignment search tool <10.1016/S0022-2836(05)80360-2>`. + + :copyright: Copyright 2015 Jon Lund Steffensen. Based on extlinks by + the Sphinx team. + :license: BSD. +""" + +from docutils import nodes, utils + +from sphinx.util.nodes import split_explicit_title + + +def reference_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): + text = utils.unescape(text) + has_explicit_title, title, part = split_explicit_title(text) + if typ in ["arXiv", "arxiv"]: + full_url = "https://arxiv.org/abs/" + part + if not has_explicit_title: + title = "arXiv:" + part + pnode = nodes.reference(title, title, internal=False, refuri=full_url) + return [pnode], [] + if typ in ["doi", "DOI"]: + full_url = "https://doi.org/" + part + if not has_explicit_title: + title = "DOI:" + part + pnode = nodes.reference(title, title, internal=False, refuri=full_url) + return [pnode], [] + + +def setup_link_role(app): + app.add_role("arxiv", reference_role, override=True) + app.add_role("arXiv", reference_role, override=True) + app.add_role("doi", reference_role, override=True) + app.add_role("DOI", reference_role, override=True) + + +def setup(app): + app.connect("builder-inited", setup_link_role) + return {"version": "0.1", "parallel_read_safe": True}