|
1 | | -####################################### |
2 | | -Quick Start with the scikit-learn-extra |
3 | | -####################################### |
| 1 | +########### |
| 2 | +Quick Start |
| 3 | +########### |
4 | 4 |
|
5 | | -This package serves as a skeleton package aiding at developing compatible |
6 | | -scikit-learn contribution. |
7 | 5 |
|
8 | | -Creating your own scikit-learn contribution package |
9 | | -=================================================== |
10 | | - |
11 | | -1. Download and setup your repository |
12 | | -------------------------------------- |
13 | | - |
14 | | -To create your package, you need to clone the ``scikit-learn-extra`` repository:: |
15 | | - |
16 | | - $ git clone https://github.com/scikit-learn-contrib/scikit-learn-extra.git |
17 | | - |
18 | | -Before to reinitialize your git repository, you need to make the following |
19 | | -changes. Replace all occurrences of ``sklearn_extra`` and ``sklearn-template`` |
20 | | -with the name of you own contribution. You can find all the occurrences using |
21 | | -the following command:: |
22 | | - |
23 | | - $ git grep sklearn_extra |
24 | | - $ git grep sklearn-template |
25 | | - |
26 | | -To remove the history of the template package, you need to remove the `.git` |
27 | | -directory:: |
28 | | - |
29 | | - $ cd scikit-learn-extra |
30 | | - $ rm -rf .git |
31 | | - |
32 | | -Then, you need to initialize your new git repository:: |
33 | | - |
34 | | - $ git init |
35 | | - $ git add . |
36 | | - $ git commit -m 'Initial commit' |
37 | | - |
38 | | -Finally, you create an online repository on GitHub and push your code online:: |
39 | | - |
40 | | - $ git remote add origin https://github.com/your_remote/your_contribution.git |
41 | | - $ git push origin master |
42 | | - |
43 | | -2. Develop your own scikit-learn estimators |
44 | | -------------------------------------------- |
45 | | - |
46 | | -.. _check_estimator: http://scikit-learn.org/stable/modules/generated/sklearn.utils.estimator_checks.check_estimator.html#sklearn.utils.estimator_checks.check_estimator |
47 | | -.. _`Contributor's Guide`: http://scikit-learn.org/stable/developers/ |
48 | | -.. _PEP8: https://www.python.org/dev/peps/pep-0008/ |
49 | | -.. _PEP257: https://www.python.org/dev/peps/pep-0257/ |
50 | | -.. _NumPyDoc: https://github.com/numpy/numpydoc |
51 | | -.. _doctests: https://docs.python.org/3/library/doctest.html |
52 | | - |
53 | | -You can modify the source files as you want. However, your custom estimators |
54 | | -need to pass the check_estimator_ test to be scikit-learn compatible. You can |
55 | | -refer to the :ref:`User Guide <user_guide>` to help you create a compatible |
56 | | -scikit-learn estimator. |
57 | | - |
58 | | -In any case, developers should endeavor to adhere to scikit-learn's |
59 | | -`Contributor's Guide`_ which promotes the use of: |
60 | | - |
61 | | -* algorithm-specific unit tests, in addition to ``check_estimator``'s common |
62 | | - tests; |
63 | | -* PEP8_-compliant code; |
64 | | -* a clearly documented API using NumpyDoc_ and PEP257_-compliant docstrings; |
65 | | -* references to relevant scientific literature in standard citation formats; |
66 | | -* doctests_ to provide succinct usage examples; |
67 | | -* standalone examples to illustrate the usage, model visualisation, and |
68 | | - benefits/benchmarks of particular algorithms; |
69 | | -* efficient code when the need for optimization is supported by benchmarks. |
70 | | - |
71 | | -3. Edit the documentation |
72 | | -------------------------- |
73 | | - |
74 | | -.. _Sphinx: http://www.sphinx-doc.org/en/stable/ |
75 | | - |
76 | | -The documentation is created using Sphinx_. In addition, the examples are |
77 | | -created using ``sphinx-gallery``. Therefore, to generate locally the |
78 | | -documentation, you are required to install the following packages:: |
79 | | - |
80 | | - $ pip install sphinx sphinx-gallery sphinx_rtd_theme matplotlib numpydoc pillow |
81 | | - |
82 | | -The documentation is made of: |
83 | | - |
84 | | -* a home page, ``doc/index.rst``; |
85 | | -* an API documentation, ``doc/api.rst`` in which you should add all public |
86 | | - objects for which the docstring should be exposed publicly. |
87 | | -* a User Guide documentation, ``doc/user_guide.rst``, containing the narrative |
88 | | - documentation of your package, to give as much intuition as possible to your |
89 | | - users. |
90 | | -* examples which are created in the `examples/` folder. Each example |
91 | | - illustrates some usage of the package. the example file name should start by |
92 | | - `plot_*.py`. |
93 | | - |
94 | | -The documentation is built with the following commands:: |
95 | | - |
96 | | - $ cd doc |
97 | | - $ make html |
98 | | - |
99 | | -4. Setup the continuous integration |
100 | | ------------------------------------ |
101 | | - |
102 | | -The project template already contains configuration files of the continuous |
103 | | -integration system. Basically, the following systems are set: |
104 | | - |
105 | | -* Travis CI is used to test the package in Linux. You need to activate Travis |
106 | | - CI for your own repository. Refer to the Travis CI documentation. |
107 | | -* AppVeyor is used to test the package in Windows. You need to activate |
108 | | - AppVeyor for your own repository. Refer to the AppVeyor documentation. |
109 | | -* Circle CI is used to check if the documentation is generated properly. You |
110 | | - need to activate Circle CI for your own repository. Refer to the Circle CI |
111 | | - documentation. |
112 | | -* ReadTheDocs is used to build and host the documentation. You need to activate |
113 | | - ReadTheDocs for your own repository. Refer to the ReadTheDocs documentation. |
114 | | -* CodeCov for tracking the code coverage of the package. You need to activate |
115 | | - CodeCov for you own repository. |
116 | | -* PEP8Speaks for automatically checking the PEP8 compliance of your project for |
117 | | - each Pull Request. |
118 | | - |
119 | | -Publish your package |
120 | | -==================== |
121 | | - |
122 | | -.. _PyPi: https://packaging.python.org/tutorials/packaging-projects/ |
123 | | -.. _conda-foge: https://conda-forge.org/ |
124 | | - |
125 | | -You can make your package available through PyPi_ and conda-forge_. Refer to |
126 | | -the associated documentation to be able to upload your packages such that |
127 | | -it will be installable with ``pip`` and ``conda``. Once published, it will |
128 | | -be possible to install your package with the following commands:: |
129 | | - |
130 | | - $ pip install your-scikit-learn-contribution |
131 | | - $ conda install -c conda-forge your-scikit-learn-contribution |
| 6 | +To add |
0 commit comments