MAINT better doc

doc/conf.py

@@ -25,6 +25,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
+    "sphinx-prompt",
     "sphinx_gallery.gen_gallery",
     "numpydoc",
 ]

doc/quick_start.rst

@@ -8,40 +8,50 @@ scikit-learn contribution.
 Creating your own scikit-learn contribution package
 ===================================================
 
-1. Download and setup your repository
--------------------------------------
+Download and setup your repository
+----------------------------------
 
-To create your package, you need to clone the ``project-template`` repository::
+To create your package, you need to clone the ``project-template`` repository:
 
-    $ git clone https://github.com/scikit-learn-contrib/project-template.git
+.. prompt:: bash $
+
+  git clone https://github.com/scikit-learn-contrib/project-template.git
 
 Before to reinitialize your git repository, you need to make the following
-changes. Replace all occurrences of ``skltemplate`` and ``sklearn-template``
-with the name of you own contribution. You can find all the occurrences using
-the following command::
+changes. Replace all occurrences of ``skltemplate``, ``sklearn-template``, or
+``project-template`` with the name of you own project. You can find all the
+occurrences using the following command:
+
+.. prompt:: bash $
 
-    $ git grep skltemplate
-    $ git grep sklearn-template
+  git grep skltemplate
+  git grep sklearn-template
+  git grep project-template
 
 To remove the history of the template package, you need to remove the `.git`
-directory::
+directory:
+
+.. prompt:: bash $
+
+  rm -rf .git
+
+Then, you need to initialize your new git repository:
 
-    $ cd project-template
-    $ rm -rf .git
+.. prompt:: bash $
 
-Then, you need to initialize your new git repository::
+  git init
+  git add .
+  git commit -m 'Initial commit'
 
-    $ git init
-    $ git add .
-    $ git commit -m 'Initial commit'
+Finally, you create an online repository on GitHub and push your code online:
 
-Finally, you create an online repository on GitHub and push your code online::
+.. prompt:: bash $
 
-    $ git remote add origin https://github.com/your_remote/your_contribution.git
-    $ git push origin master
+  git remote add origin https://github.com/your_remote/your_contribution.git
+  git push origin main
 
-2. Develop your own scikit-learn estimators
--------------------------------------------
+Develop your own scikit-learn estimators
+----------------------------------------
 
 .. _check_estimator: http://scikit-learn.org/stable/modules/generated/sklearn.utils.estimator_checks.check_estimator.html#sklearn.utils.estimator_checks.check_estimator
 .. _`Contributor's Guide`: http://scikit-learn.org/stable/developers/
@@ -51,8 +61,10 @@ Finally, you create an online repository on GitHub and push your code online::
 .. _doctests: https://docs.python.org/3/library/doctest.html
 
 You can modify the source files as you want. However, your custom estimators
-need to pass the check_estimator_ test to be scikit-learn compatible. You can
-refer to the :ref:`User Guide <user_guide>` to help you create a compatible
+need to pass the check_estimator_ test to be scikit-learn compatible. We provide a
+file called `test_common.py` where we run the checks on our custom estimators.
+
+You can refer to the :ref:`User Guide <user_guide>` to help you create a compatible
 scikit-learn estimator.
 
 In any case, developers should endeavor to adhere to scikit-learn's
@@ -68,16 +80,28 @@ In any case, developers should endeavor to adhere to scikit-learn's
   benefits/benchmarks of particular algorithms;
 * efficient code when the need for optimization is supported by benchmarks.
 
-3. Edit the documentation
--------------------------
+Managing your local and continuous integration environment
+----------------------------------------------------------
+
+Here, we set up for you an repository that uses `pixi`. The `pixi.toml` file defines
+the packages and tasks to be run that we will present below. You can refer to the
+following documentation link to install `pixi`: https://pixi.sh/latest/#installation
+
+Once done, you can refer to the documentation to get started but we provide the
+command below to interact with the main task requested to develop your package.
+
+Edit the documentation
+----------------------
 
 .. _Sphinx: http://www.sphinx-doc.org/en/stable/
 
 The documentation is created using Sphinx_. In addition, the examples are
 created using ``sphinx-gallery``. Therefore, to generate locally the
-documentation, you are required to install the following packages::
+documentation, you can leverage the following `pixi` task:
 
-    $ pip install sphinx sphinx-gallery sphinx_rtd_theme matplotlib numpydoc pillow
+.. prompt:: bash $
+
+  pixi run build-doc
 
 The documentation is made of:
 
@@ -91,30 +115,34 @@ The documentation is made of:
   illustrates some usage of the package. the example file name should start by
   `plot_*.py`.
 
-The documentation is built with the following commands::
+Local testing
+-------------
+
+To run the tests locally, you can use the following command:
+
+.. prompt:: bash $
+
+  pixi run test
+
+It will use `pytest` under the hood to run the package tests.
 
-    $ cd doc
-    $ make html
+In addition, you have a linter task to check the code consistency in terms of style:
 
-4. Setup the continuous integration
------------------------------------
+.. prompt:: bash $
+
+  pixi run lint
+
+Setup the continuous integration
+--------------------------------
 
 The project template already contains configuration files of the continuous
-integration system. Basically, the following systems are set:
-
-* Travis CI is used to test the package in Linux. You need to activate Travis
-  CI for your own repository. Refer to the Travis CI documentation.
-* AppVeyor is used to test the package in Windows. You need to activate
-  AppVeyor for your own repository. Refer to the AppVeyor documentation.
-* Circle CI is used to check if the documentation is generated properly. You
-  need to activate Circle CI for your own repository. Refer to the Circle CI
-  documentation.
-* ReadTheDocs is used to build and host the documentation. You need to activate
-  ReadTheDocs for your own repository. Refer to the ReadTheDocs documentation.
-* CodeCov for tracking the code coverage of the package. You need to activate
-  CodeCov for you own repository.
-* PEP8Speaks for automatically checking the PEP8 compliance of your project for
-  each Pull Request.
+integration system. It leverage the above pixi commands and run on GitHub Actions.
+In short, it will:
+
+* run the tests on the different platforms (Linux, MacOS, Windows) and upload the
+  coverage report to codecov.io;
+* check the code style (linter);
+* build the documentation and deploy it automatically on GitHub Pages.
 
 Publish your package
 ====================
@@ -124,8 +152,4 @@ Publish your package
 
 You can make your package available through PyPi_ and conda-forge_. Refer to
 the associated documentation to be able to upload your packages such that
-it will be installable with ``pip`` and ``conda``. Once published, it will
-be possible to install your package with the following commands::
-
-    $ pip install your-scikit-learn-contribution
-    $ conda install -c conda-forge your-scikit-learn-contribution
+it will be installable with ``pip`` and ``conda``.

examples/plot_classifier.py

@@ -5,41 +5,37 @@
 
 An example plot of :class:`skltemplate.template.TemplateClassifier`
 """
-import numpy as np
-from matplotlib import pyplot as plt
 
+# %%
+# Train our classifier on very simple dataset
 from skltemplate import TemplateClassifier
 
 X = [[0, 0], [1, 1]]
 y = [0, 1]
-clf = TemplateClassifier()
-clf.fit(X, y)
+clf = TemplateClassifier().fit(X, y)
+
+# %%
+# Create a test dataset
+import numpy as np
 
 rng = np.random.RandomState(13)
 X_test = rng.rand(500, 2)
-y_pred = clf.predict(X_test)
-
-X_0 = X_test[y_pred == 0]
-X_1 = X_test[y_pred == 1]
-
 
-p0 = plt.scatter(0, 0, c="red", s=100)
-p1 = plt.scatter(1, 1, c="blue", s=100)
-
-ax0 = plt.scatter(X_0[:, 0], X_0[:, 1], c="crimson", s=50)
-ax1 = plt.scatter(X_1[:, 0], X_1[:, 1], c="deepskyblue", s=50)
-
-leg = plt.legend(
-    [p0, p1, ax0, ax1],
-    ["Point 0", "Point 1", "Class 0", "Class 1"],
-    loc="upper left",
-    fancybox=True,
-    scatterpoints=1,
+# %%
+# Use scikit-learn to display the decision boundary
+from sklearn.inspection import DecisionBoundaryDisplay
+
+disp = DecisionBoundaryDisplay.from_estimator(clf, X_test)
+disp.ax_.scatter(
+    X_test[:, 0],
+    X_test[:, 1],
+    c=clf.predict(X_test),
+    s=20,
+    edgecolors="k",
+    linewidths=0.5,
+)
+disp.ax_.set(
+    xlabel="Feature 1",
+    ylabel="Feature 2",
+    title="Template Classifier Decision Boundary",
 )
-leg.get_frame().set_alpha(0.5)
-
-plt.xlabel("Feature 1")
-plt.ylabel("Feature 2")
-plt.xlim([-0.5, 1.5])
-
-plt.show()

pixi.lock

@@ -286,6 +286,7 @@ environments:
       - conda: https://conda.anaconda.org/conda-forge/noarch/soupsieve-2.5-pyhd8ed1ab_1.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-7.3.7-pyhd8ed1ab_0.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-gallery-0.16.0-pyhd8ed1ab_0.conda
+      - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-prompt-1.4.0-pyhd8ed1ab_0.tar.bz2
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-applehelp-1.0.8-pyhd8ed1ab_0.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-devhelp-1.0.6-pyhd8ed1ab_0.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-htmlhelp-2.0.5-pyhd8ed1ab_0.conda
@@ -402,6 +403,7 @@ environments:
       - conda: https://conda.anaconda.org/conda-forge/noarch/soupsieve-2.5-pyhd8ed1ab_1.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-7.3.7-pyhd8ed1ab_0.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-gallery-0.16.0-pyhd8ed1ab_0.conda
+      - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-prompt-1.4.0-pyhd8ed1ab_0.tar.bz2
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-applehelp-1.0.8-pyhd8ed1ab_0.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-devhelp-1.0.6-pyhd8ed1ab_0.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-htmlhelp-2.0.5-pyhd8ed1ab_0.conda
@@ -500,6 +502,7 @@ environments:
       - conda: https://conda.anaconda.org/conda-forge/noarch/soupsieve-2.5-pyhd8ed1ab_1.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-7.3.7-pyhd8ed1ab_0.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-gallery-0.16.0-pyhd8ed1ab_0.conda
+      - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-prompt-1.4.0-pyhd8ed1ab_0.tar.bz2
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-applehelp-1.0.8-pyhd8ed1ab_0.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-devhelp-1.0.6-pyhd8ed1ab_0.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-htmlhelp-2.0.5-pyhd8ed1ab_0.conda
@@ -627,6 +630,7 @@ environments:
       - conda: https://conda.anaconda.org/conda-forge/noarch/soupsieve-2.5-pyhd8ed1ab_1.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-7.3.7-pyhd8ed1ab_0.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-gallery-0.16.0-pyhd8ed1ab_0.conda
+      - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-prompt-1.4.0-pyhd8ed1ab_0.tar.bz2
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-applehelp-1.0.8-pyhd8ed1ab_0.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-devhelp-1.0.6-pyhd8ed1ab_0.conda
       - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-htmlhelp-2.0.5-pyhd8ed1ab_0.conda
@@ -7550,6 +7554,25 @@ packages:
   - pkg:pypi/sphinx-gallery
   size: 376506
   timestamp: 1714467900533
+- kind: conda
+  name: sphinx-prompt
+  version: 1.4.0
+  build: pyhd8ed1ab_0
+  subdir: noarch
+  noarch: python
+  url: https://conda.anaconda.org/conda-forge/noarch/sphinx-prompt-1.4.0-pyhd8ed1ab_0.tar.bz2
+  sha256: 3690b4b70322adc77f18c2b31545ddbbe69f1627de76ea9deace8c9809550bab
+  md5: 88ee91e8679603f2a5bd036d52919cc2
+  depends:
+  - pygments
+  - python >=3.0
+  - sphinx
+  license: BSD-3-Clause
+  license_family: BSD
+  purls:
+  - pkg:pypi/sphinx-prompt
+  size: 8196
+  timestamp: 1616424811736
 - kind: conda
   name: sphinxcontrib-applehelp
   version: 1.0.8

pixi.toml

@@ -39,6 +39,7 @@ numpydoc = "*"
 pydata-sphinx-theme = "*"
 sphinx = "*"
 sphinx-gallery = "*"
+sphinx-prompt = "*"
 
 [feature.doc.tasks]
 build-doc = { cmd = "make html", cwd = "doc" }