Skip to content

Commit a93abac

Browse files
glemaitreglemaitre
committed
DOC: Update the documentation
1 parent 837dfaf commit a93abac

File tree

2 files changed

+134
-251
lines changed

2 files changed

+134
-251
lines changed

‎README.rst

Lines changed: 7 additions & 250 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@
1414
.. |CircleCI| image:: https://circleci.com/gh/scikit-learn-contrib/project-template.svg?style=shield&circle-token=:circle-token
1515
.. _CircleCI: https://circleci.com/gh/scikit-learn-contrib/project-template/tree/master
1616

17+
.. |ReadTheDocs| .. image:: https://readthedocs.org/projects/sklearn-template/badge/?version=latest
18+
.. _ReadTheDocs: https://sklearn-template.readthedocs.io/en/latest/?badge=latest
19+
20+
1721
project-template - A template for scikit-learn contributions
1822
============================================================
1923

@@ -25,256 +29,9 @@ and (hyper)parameter search, while facilitating testing (including some API
2529
compliance), documentation, open source development, packaging, and continuous
2630
integration.
2731

28-
Important Links
29-
---------------
30-
31-
HTML Documentation_
32-
33-
.. _documentation: http://contrib.scikit-learn.org/project-template/
34-
35-
Installation and Usage
36-
----------------------
37-
38-
The package by itself comes with a single module and an estimator. Before
39-
installing the module you will need `numpy` and `scipy`.
40-
To install the module execute::
41-
42-
pip install sklearn-template
43-
44-
If the installation is successful, and `scikit-learn` is correctly installed,
45-
you should be able to execute the following in Python::
46-
47-
>>> from skltemplate import TemplateEstimator
48-
>>> estimator = TemplateEstimator()
49-
>>> estimator.fit(np.arange(10).reshape(10, 1), np.arange(10))
50-
51-
`TemplateEstimator` by itself does nothing useful, but it serves as an example
52-
of how other Estimators should be written. It also comes with its own unit
53-
tests under `skltemplate/tests` which can be run using `py.test`.
54-
55-
Creating your own library
56-
-------------------------
57-
58-
1. Cloning
59-
~~~~~~~~~~
60-
61-
Clone the project into your computer by executing::
62-
63-
$ git clone https://github.com/scikit-learn-contrib/project-template.git
64-
65-
You should rename the `project-template` folder to the name of your project.
66-
To host the project on Github, visit https://github.com/new and create a new
67-
repository. To upload your project on Github execute::
68-
69-
$ git remote set-url origin https://github.com/username/project-name.git
70-
$ git push origin master
71-
72-
2. Modifying the Source
73-
~~~~~~~~~~~~~~~~~~~~~~~
74-
75-
You are free to modify the source as you want, but at the very least, all your
76-
estimators should pass the
77-
[`check_estimator`](http://scikit-learn.org/stable/modules/generated/sklearn.utils.estimator_checks.check_estimator.html#sklearn.utils.estimator_checks.check_estimator)
78-
test to be scikit-learn compatible. (If there are valid reasons your estimator
79-
cannot pass `check_estimator`, please [raise an
80-
issue](https://github.com/scikit-learn/scikit-learn/issues/new) at scikit-learn
81-
so we can make `check_estimator` more flexible.)
82-
83-
This template is particularly useful for publishing open-source versions of
84-
algorithms that do not meet the criteria for inclusion in the core scikit-learn
85-
package (see [FAQ](http://scikit-learn.org/stable/faq.html)), such as recent
86-
and unpopular developments in machine learning.
87-
However, developing using this template may also be a stepping stone to
88-
eventual inclusion in the core package.
89-
90-
In any case, developers should endeavor to adhere to scikit-learn's
91-
[Contributor's Guide](http://scikit-learn.org/stable/developers/) which promotes
92-
the use of:
93-
94-
* algorithm-specific unit tests, in addition to `check_estimator`'s common tests
95-
* [PEP8](https://www.python.org/dev/peps/pep-0008/)-compliant code
96-
* a clearly documented API using [NumpyDoc](https://github.com/numpy/numpydoc)
97-
and [PEP257](https://www.python.org/dev/peps/pep-0257/)-compliant docstrings
98-
* references to relevant scientific literature in standard citation formats
99-
* [doctests](https://docs.python.org/3/library/doctest.html) to provide
100-
succinct usage examples
101-
* standalone examples to illustrate the usage, model visualisation, and
102-
benefits/benchmarks of particular algorithms
103-
* efficient code when the need for optimization is supported by benchmarks
104-
105-
3. Modifying the Documentation
106-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
107-
108-
The documentation is built using [sphinx](http://www.sphinx-doc.org/en/stable/).
109-
It incorporates narrative documentation from the `doc/` directory, standalone
110-
examples from the `examples/` directory, and API reference compiled from
111-
estimator docstrings.
112-
113-
To build the documentation locally, ensure that you have `sphinx`,
114-
`sphinx-gallery` and `matplotlib` by executing::
115-
116-
$ pip install sphinx matplotlib sphinx-gallery
117-
118-
The documentation contains a home page (`doc/index.rst`), an API documentation
119-
page (`doc/api.rst`) and a page documenting the `template` module
120-
(`doc/template.rst`). Sphinx allows you to automatically document your modules
121-
and classes by using the `autodoc` directive (see `template.rst`). To change
122-
the asthetics of the docs and other paramteres, edit the `doc/conf.py` file.
123-
For more information visit the [Sphinx
124-
Documentation](http://www.sphinx-doc.org/en/stable/contents.html).
125-
126-
You can also add code examples in the `examples` folder. All files inside
127-
the folder of the form `plot_*.py` will be executed and their generated
128-
plots will be available for viewing in the `/auto_examples` URL.
129-
130-
To build the documentation locally execute::
131-
132-
$ cd doc
133-
$ make html
134-
135-
4. Setting up Travis CI
136-
~~~~~~~~~~~~~~~~~~~~~~~
137-
138-
[TravisCI](https://travis-ci.org/) allows you to continuously build and test
139-
your code from Github to ensure that no code-breaking changes are pushed. After
140-
you sign up and authourize TravisCI, add your new repository to TravisCI so that
141-
it can start building it. The `travis.yml` contains the configuration required
142-
for Travis to build the project. You will have to update the variable `MODULE`
143-
with the name of your module for Travis to test it. Once you add the project on
144-
TravisCI, all subsequent pushes on the master branch will trigger a Travis
145-
build. By default, the project is tested on Python 2.7 and Python 3.5.
146-
147-
5. Setting up Coveralls
148-
~~~~~~~~~~~~~~~~~~~~~~~
149-
150-
[Coveralls](https://coveralls.io/) reports code coverage statistics of your
151-
tests on each push. Sign up on Coveralls and add your repository so that
152-
Coveralls can start monitoring it. The project already contains the required
153-
configuration for Coveralls to work. All subsequent builds after adding your
154-
project will generate a coverage report.
155-
156-
6. Setting up Appveyor
157-
~~~~~~~~~~~~~~~~~~~~~~
158-
159-
[Appveyor](https://www.appveyor.com/) provides continuous intergration on the
160-
windows platform. Currently, Appveyor can also be used to build platform
161-
specific Windows wheels, which can be uploaded to a Cloud Service provider and
162-
be made available via a Content Delivery Network (CDN). To setup Appveyor to
163-
build your project you need to sign up on Appveyor and authorize it. Appveyor
164-
configaration is governed by the `appveyor.yml` file. You have to change the
165-
following variables in it to match the requirements of your project.
166-
167-
| Variable | Value|
168-
|----------|------|
169-
| `PROJECT_NAME` | The name of your project. This should be the same as the `name` field in `setup.py` |
170-
| `MODULE` | The name of the module you want to be tested |
171-
| `CLOUD_STORAGE` | A constant which indicates which Cloud Storage service provider to use. It should be one among the [Supported Providers](https://libcloud.readthedocs.io/en/latest/storage/supported_providers.html) |
172-
| `CLOUD_CONTAINER` | The name of a container with your Cloud Storage service provider where the built files will be uploaded.|
173-
| `WHEELHOUSE_UPLOADER_USERNAME` | The username you have used to register with your Cloud Storage procider |
174-
| `WHEELHOUSE_UPLOADER_SECRET` | An API key you have obtained from your Cloud Storage provider, which will authenticate you to upload files to it. This should **never** be stored in plain text. To make Appveyor encrypt your API key, use Appveyor's [Encrypt Tool](https://ci.appveyor.com/tools/encrypt) and store the returned value using a `secure:` prefix. |
175-
176-
Maintainers of an official [scikit-learn contrib](
177-
https://contrib.scikit-learn.org) repository can request [Rackspace]
178-
(https://mycloud.rackspace.com/) credentials from the scikit-learn developers.
179-
180-
181-
7. Setting up Circle CI
182-
~~~~~~~~~~~~~~~~~~~~~~~
183-
184-
The project uses [CircleCI](https://circleci.com/) to build its documentation
185-
from the `master` branch and host it using [Github Pages](https://pages.github.com/).
186-
Again, you will need to Sign Up and authorize CircleCI. The configuration
187-
of CircleCI is governed by the `circle.yml` file, which needs to be mofified
188-
if you want to setup the docs on your own website. The values to be changed
189-
are
190-
191-
| Variable | Value|
192-
|----------|------|
193-
| `USERNAME` | The name of the user or organization of the repository where the project and documentation is hosted |
194-
| `DOC_REPO` | The repository where the documentation will be hosted. This can be the same as the project repository |
195-
| `DOC_URL` | The relative URL where the documentation will be hosted |
196-
| `EMAIL` | The email id to use while pushing the documentation, this can be any valid email address |
197-
198-
In addition to this, you will need to grant access to the CircleCI computers
199-
to push to your documentation repository. To do this, visit the Project Settings
200-
page of your project in CircleCI. Select `Checkout SSH keys` option and then
201-
choose `Create and add user key` option. This should grant CircleCI privileges
202-
to push to the repository `https://github.com/USERNAME/DOC_REPO/`.
203-
204-
If all goes well, you should be able to visit the documentation of your project
205-
on::
206-
207-
https://github.com/USERNAME/DOC_REPO/DOC_URL
208-
209-
210-
8. Adding Badges
211-
~~~~~~~~~~~~~~~~
212-
213-
Follow the instructions to add a [Travis Badge](https://docs.travis-ci.com/user/status-images/),
214-
[Coveralls Badge](https://coveralls.io) and
215-
[CircleCI Badge](https://circleci.com/docs/status-badges) to your repository's
216-
`README`.
217-
218-
9. Advertising your package
219-
~~~~~~~~~~~~~~~~~~~~~~~~~~~
220-
221-
Once your work is mature enough for the general public to use it, you should
222-
submit a Pull Request to modify scikit-learn's
223-
[related projects listing](https://github.com/scikit-learn/scikit-learn/edit/master/doc/related_projects.rst).
224-
Please insert brief description of your project and a link to its code
225-
repository or PyPI page.
226-
You may also wish to announce your work on the
227-
[`scikit-learn-general` mailing list](https://lists.sourceforge.net/lists/listinfo/scikit-learn-general).
228-
229-
10. Uploading your package to PyPI
230-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
231-
232-
Uploading your package to [PyPI](https://pypi.python.org/pypi) allows users to
233-
install your package through `pip`. Python provides two repositories to upload
234-
your packages. The [PyPI Test](https://testpypi.python.org/pypi) repository,
235-
which is to be used for testing packages before their release, and the
236-
[PyPI](https://pypi.python.org/pypi) repository, where you can make your
237-
releases. You need to register a username and password with both these sites.
238-
The username and passwords for both these sites need not be the same. To upload
239-
your package through the command line, you need to store your username and
240-
password in a file called `.pypirc` in your `$HOME` directory with the
241-
following format::
242-
243-
[distutils]
244-
index-servers =
245-
pypi
246-
pypitest
247-
248-
[pypi]
249-
repository=https://pypi.python.org/pypi
250-
username=<your-pypi-username>
251-
password=<your-pypi-passowrd>
252-
253-
[pypitest]
254-
repository=https://testpypi.python.org/pypi
255-
username=<your-pypitest-username>
256-
password=<your-pypitest-passowrd>
257-
258-
Make sure that all details in `setup.py` are up to date. To upload your package
259-
to the Test server, execute::
260-
261-
$ python setup.py register -r pypitest
262-
$ python setup.py sdist upload -r pypitest
263-
264-
Your package should now be visible on: https://testpypi.python.org/pypi
265-
266-
To install a package from the test server, execute:
267-
268-
$ pip install -i https://testpypi.python.org/pypi <package-name>
269-
270-
271-
Similary, to upload your package to the PyPI server execute
272-
273-
$ python setup.py register -r pypi
274-
$ python setup.py sdist upload -r pypi
275-
276-
To install your package, execute:
32+
.. _documentation: https://sklearn-template.readthedocs.io/en/latest/quick_start.html
27733

278-
$ pip install <package-name>
34+
Refer to the documentation_ to modify the template for your own scikit-learn
35+
contribution.
27936

28037
*Thank you for cleanly contributing to the scikit-learn ecosystem!*

0 commit comments

Comments
 (0)