Quick Start with the project-template¶
This package serves as a skeleton package aiding at developing compatible scikit-learn contribution.
Creating your own scikit-learn contribution package¶
1. Download and setup your repository¶
To create your package, you need to clone the project-template
repository:
$ 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:
$ git grep skltemplate
$ git grep sklearn-template
To remove the history of the template package, you need to remove the .git directory:
$ cd project-template
$ rm -rf .git
Then, you need to initialize your new git repository:
$ git init
$ git add .
$ git commit -m 'Initial commit'
Finally, you create an online repository on GitHub and push your code online:
$ git remote add origin https://github.com/your_remote/your_contribution.git
$ git push origin master
2. Develop your own scikit-learn estimators¶
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 User Guide to help you create a compatible scikit-learn estimator.
In any case, developers should endeavor to adhere to scikit-learn’s Contributor’s Guide which promotes the use of:
algorithm-specific unit tests, in addition to
check_estimator
’s common tests;PEP8-compliant code;
a clearly documented API using NumpyDoc and PEP257-compliant docstrings;
references to relevant scientific literature in standard citation formats;
doctests to provide succinct usage examples;
standalone examples to illustrate the usage, model visualisation, and benefits/benchmarks of particular algorithms;
efficient code when the need for optimization is supported by benchmarks.
3. Edit the documentation¶
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:
$ pip install sphinx sphinx-gallery sphinx_rtd_theme matplotlib numpydoc pillow
The documentation is made of:
a home page,
doc/index.rst
;an API documentation,
doc/api.rst
in which you should add all public objects for which the docstring should be exposed publicly.a User Guide documentation,
doc/user_guide.rst
, containing the narrative documentation of your package, to give as much intuition as possible to your users.examples which are created in the examples/ folder. Each example illustrates some usage of the package. the example file name should start by plot_*.py.
The documentation is built with the following commands:
$ cd doc
$ make html
4. 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.
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