From b388a2fb8d8fe58db25a02a1b380b462743bfec3 Mon Sep 17 00:00:00 2001 From: Vighnesh Birodkar Date: Fri, 15 Jan 2016 15:54:59 -0500 Subject: [PATCH] changed ls command debug echo selective remove files corrected badges title of homepage nojekyll and not delete files before doc update change username reset doc url to blank doc url test change doc header name dfx option modify doc pushing url typo remove last few traces of stub corrected readme to refer to skltemplate renames top level module to skltemplate grammar correction in readme merge changes from origin change name in docs Initial renaming stub to template Merge pull request #3 from jnothman/patch-1 Note about improving check_estimator Typos Changed forking to cloning correct typo remove -i added pypi instructions changed package name updated readme link changed harcoded module name renames scripts folder and avoided hard coding in test.sh Merge pull request #2 from jnothman/readme DOC Assorted fixes and additions to README added gallery installation to readme installing sphinx-gallery Build gallery using sphinx gallery removed user guide file moved user guide in readme doc clrifications use macro instead of hard code clarified numpy installation guide enh user guide changes elaborated circleCI section testing tables set vars in circle.yml added branch command var names in push doc Added nose line Added coveralls info Added forking and CI instructions changed user guide to markdown Create user_guide.rst installation chances and macro for docs url added link to docs changed badge style added circle ci badge doc change add docs properly only add docs folder force clean properly force clean added clean command forced checkout git changes added extra slash move via tmp folder remove deletion command reenable pushing script copy files from inside html folder doc prefix debug changes forced checkout added debug find command chnaged git commands dir changes modified push_doc changed push url loc corrected spelling name correction install pillow added doc push script try removing pythonpath changed install to develop added clean command install sklearn corrected sphinx command make pip install dependencies removed the user option from install fixed import for python 3 fixed tests made build branch master renamed circle.yml added circle yml added nature theme genete example plots added sphinx doc files added docstrings added own links rename to rst added sklearns doc added rst mode changed readme to show badges create success script no timer in tests specify test dir added coverage command removed mpl from requirements make conda install mpl changed cython version use miniconda travis changed added travis yml moved and renamed things added tests Added DemoEstimator corrected import nose correction requirements correction remove setup requires option added import warnings adde numpy scipy and cython to setup requires added sklearn to requirements added requirements created python package Initial commit --- .gitignore | 66 +++++++ .nojekyll | 0 .travis.yml | 23 +++ LICENSE | 27 +++ MANIFEST.in | 1 + README.md | 229 ++++++++++++++++++++++ ci_scripts/install.sh | 40 ++++ ci_scripts/push_doc.sh | 49 +++++ ci_scripts/success.sh | 13 ++ ci_scripts/test.sh | 13 ++ circle.yml | 56 ++++++ doc/Makefile | 184 ++++++++++++++++++ doc/api.rst | 4 + doc/conf.py | 302 +++++++++++++++++++++++++++++ doc/index.rst | 31 +++ doc/make.bat | 242 +++++++++++++++++++++++ doc/template.rst | 7 + examples/README.txt | 6 + examples/plot_template.py | 17 ++ requirements.txt | 2 + setup.cfg | 2 + setup.py | 28 +++ skltemplate/__init__.py | 4 + skltemplate/template.py | 50 +++++ skltemplate/tests/test_common.py | 5 + skltemplate/tests/test_template.py | 11 ++ 26 files changed, 1412 insertions(+) create mode 100644 .gitignore create mode 100644 .nojekyll create mode 100644 .travis.yml create mode 100644 LICENSE create mode 100644 MANIFEST.in create mode 100644 README.md create mode 100644 ci_scripts/install.sh create mode 100644 ci_scripts/push_doc.sh create mode 100644 ci_scripts/success.sh create mode 100644 ci_scripts/test.sh create mode 100644 circle.yml create mode 100644 doc/Makefile create mode 100644 doc/api.rst create mode 100644 doc/conf.py create mode 100644 doc/index.rst create mode 100644 doc/make.bat create mode 100644 doc/template.rst create mode 100644 examples/README.txt create mode 100644 examples/plot_template.py create mode 100644 requirements.txt create mode 100644 setup.cfg create mode 100644 setup.py create mode 100644 skltemplate/__init__.py create mode 100644 skltemplate/template.py create mode 100644 skltemplate/tests/test_common.py create mode 100644 skltemplate/tests/test_template.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..395b291 --- /dev/null +++ b/.gitignore @@ -0,0 +1,66 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# scikit-learn specific +doc/_build/ +doc/auto_examples/ +doc/modules/generated/ +doc/datasets/generated/ + +# Distribution / packaging + +.Python +env/ +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +*.egg-info/ +.installed.cfg +*.egg + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*,cover +.hypothesis/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..a95c328 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,23 @@ +language: python + +cache: + apt: true + # We use three different cache directory + # to work around a Travis bug with multi-platform cache + directories: + - $HOME/.cache/pip + - $HOME/download +env: + global: + # Directory where tests are run from + - TEST_DIR=/tmp/test_dir/ + - MODULE=skltemplate + matrix: + - DISTRIB="conda" PYTHON_VERSION="2.7" + NUMPY_VERSION="1.6.2" SCIPY_VERSION="0.11.0" CYTHON_VERSION="0.21" + - DISTRIB="conda" PYTHON_VERSION="3.5" COVERAGE="true" + NUMPY_VERSION="1.10.1" SCIPY_VERSION="0.16.0" CYTHON_VERSION="0.23.4" + +install: source ci_scripts/install.sh +script: bash ci_scripts/test.sh +after_success: source ci_scripts/success.sh diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..d208be4 --- /dev/null +++ b/LICENSE @@ -0,0 +1,27 @@ +Copyright (c) 2016, Vighnesh Birodkar +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +* Neither the name of project-template nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..f9bd145 --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1 @@ +include requirements.txt diff --git a/README.md b/README.md new file mode 100644 index 0000000..3600a85 --- /dev/null +++ b/README.md @@ -0,0 +1,229 @@ +#project-template - A template for scikit-learn extensions + +[![Travis Status](https://travis-ci.org/scikit-learn-contrib/project-template.svg?branch=master)](https://travis-ci.org/scikit-learn-contrib/project-template) +[![Coveralls Status](https://coveralls.io/repos/scikit-learn-contrib/project-template/badge.svg?branch=master&service=github)](https://coveralls.io/r/scikit-learn-contrib/project-template) +[![CircleCI Status](https://circleci.com/gh/scikit-learn-contrib/project-template.svg?style=shield&circle-token=:circle-token)](https://circleci.com/gh/scikit-learn-contrib/project-template/tree/master) + +**project-template** is a template project for +[scikit-learn](http://scikit-learn.org/) +compatible extensions. + +It aids development of estimators that can be used in scikit-learn pipelines +and (hyper)parameter search, while facilitating testing (including some API +compliance), documentation, open source development, packaging, and continuous +integration. + +## Important Links +HTML Documentation - http://vighneshbirodkar.github.io/project-template/docs/ + +## Installation and Usage +The package by itself comes with a single module and an estimator. Before +installing the module you will need `numpy` and `scipy`. +To install the module execute: +```shell +$ python setup.py install +``` +or +``` +pip install sklearn-template +``` + +If the installation is successful, and `scikit-learn` is correctly installed, +you should be able to execute the following in Python: +```python +>>> from skltemplate import TemplateEstimator +>>> estimator = TemplateEstimator() +>>> estimator.fit(np.arange(10), np.arange(10)) +``` + +`TemplateEstimator` by itself does nothing useful, but it serves as an example +of how other Estimators should be written. It also comes with its own unit +tests under `template/tests` which can be run using `nosetests`. + +## Creating your own library + +### 1. Cloning +Clone the project into your computer by executing +```shell +$ git clone https://github.com/vighneshbirodkar/project-template.git +``` +You should rename the `project-template` folder to the name of your project. +To host the project on Github, visit https://github.com/new and create a new +repository. To upload your project on Github execute +```shell +$ git remote add origin https://github.com/username/project-name.git +$ git push origin master +``` + +### 2. Modifying the Source +You are free to modify the source as you want, but at the very least, all your +estimators should pass the [`check_estimator`](http://scikit-learn.org/stable/modules/generated/sklearn.utils.estimator_checks.check_estimator.html#sklearn.utils.estimator_checks.check_estimator) +test to be scikit-learn compatible. +(If there are valid reasons your estimator cannot pass `check_estimator`, please +[raise an issue](https://github.com/scikit-learn/scikit-learn/issues/new) at +scikit-learn so we can make `check_estimator` more flexible.) + +This template is particularly useful for publishing open-source versions of +algorithms that do not meet the criteria for inclusion in the core scikit-learn +package (see [FAQ](http://scikit-learn.org/stable/faq.html)), such as recent +and unpopular developments in machine learning. +However, developing using this template may also be a stepping stone to +eventual inclusion in the core package. + +In any case, developers should endeavor to adhere to scikit-learn's +[Contributor's Guide](http://scikit-learn.org/stable/developers/) which promotes +the use of: +* algorithm-specific unit tests, in addition to `check_estimator`'s common tests +* [PEP8](https://www.python.org/dev/peps/pep-0008/)-compliant code +* a clearly documented API using [NumpyDoc](https://github.com/numpy/numpydoc) + and [PEP257](https://www.python.org/dev/peps/pep-0257/)-compliant docstrings +* references to relevant scientific literature in standard citation formats +* [doctests](https://docs.python.org/3/library/doctest.html) 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. Modifying the Documentation + +The documentation is built using [sphinx](http://www.sphinx-doc.org/en/stable/). +It incorporates narrative documentation from the `doc/` directory, standalone +examples from the `examples/` directory, and API reference compiled from +estimator docstrings. + +To build the documentation locally, ensure that you have `sphinx`, +`sphinx-gallery` and `matplotlib` by executing: +```shell +$ pip install sphinx matplotlib sphinx-gallery +``` +The documentation contains a home page (`doc/index.rst`), an API +documentation page (`doc/api.rst`) and a page documenting the `template` module +(`doc/template.rst`). Sphinx allows you to automatically document your modules +and classes by using the `autodoc` directive (see `template.rst`). To change the +asthetics of the docs and other paramteres, edit the `doc/conf.py` file. For +more information visit the [Sphinx Documentation](http://www.sphinx-doc.org/en/stable/contents.html). + +You can also add code examples in the `examples` folder. All files inside +the folder of the form `plot_*.py` will be executed and their generated +plots will be available for viewing in the `/auto_examples` URL. + +To build the documentation locally execute +```shell +$ cd doc +$ make html +``` + +### 4. Setting up Travis CI +[TravisCI](https://travis-ci.org/) allows you to continuously build and test +your code from Github to ensure that no code-breaking changes are pushed. After +you sign up and authourize TravisCI, add your new repository to TravisCI so that +it can start building it. The `travis.yml` contains the configuration required +for Travis to build the project. You will have to update the variable `MODULE` +with the name of your module for Travis to test it. Once you add the project on +TravisCI, all subsequent pushes on the master branch will trigger a Travis +build. By default, the project is tested on Python 2.7 and Python 3.5. + +### 5. Setting up Coveralls +[Coveralls](https://coveralls.io/) reports code coverage statistics of your +tests on each push. Sign up on Coveralls and add your repository so that +Coveralls can start monitoring it. The project already contains the required +configuration for Coveralls to work. All subsequent builds after adding your +project will generate a coverage report. + +### 6. Setting up Circle CI +The project uses [CircleCI](https://circleci.com/) to build its documentation +from the `master` branch and host it using [Github Pages](https://pages.github.com/). +Again, you will need to Sign Up and authorize CircleCI. The configuration +of CircleCI is governed by the `circle.yml` file, which needs to be mofified +if you want to setup the docs on your own website. The values to be changed +are + +| Variable | Value| +|----------|------| +| `USERNAME` | The name of the user or organization of the repository where the project and documentation is hosted | +| `DOC_REPO` | The repository where the documentation will be hosted. This can be the same as the project repository | +| `DOC_URL` | The relative URL where the documentation will be hosted | +| `EMAIL` | The email id to use while pushing the documentation, this can be any valid email address | + +In addition to this, you will need to grant access to the CircleCI computers +to push to your documentation repository. To do this, visit the Project Settings +page of your project in CircleCI. Select `Checkout SSH keys` option and then +choose `Create and add user key` option. This should grant CircleCI privileges +to push to the repository `https://github.com/USERNAME/DOC_REPO/`. + +If all goes well, you should be able to visit the documentation of your project +on +``` +https://github.com/USERNAME/DOC_REPO/DOC_URL +``` + +### 7. Adding Badges + +Follow the instructions to add a [Travis Badge](https://docs.travis-ci.com/user/status-images/), +[Coveralls Badge](https://coveralls.io) and +[CircleCI Badge](https://circleci.com/docs/status-badges) to your repository's +`README`. + +### 8. Advertising your package + +Once your work is mature enough for the general public to use it, you should +submit a Pull Request to modify scikit-learn's +[related projects listing](https://github.com/scikit-learn/scikit-learn/edit/master/doc/related_projects.rst). +Please insert brief description of your project and a link to its code +repository or PyPI page. +You may also wish to announce your work on the +[`scikit-learn-general` mailing list](https://lists.sourceforge.net/lists/listinfo/scikit-learn-general). + +### 9. Uploading your package to PyPI + +Uploading your package to [PyPI](https://pypi.python.org/pypi) allows users to +install your package through `pip`. Python provides two repositories to upload +your packages. The [PyPI Test](https://testpypi.python.org/pypi) repository, +which is to be used for testing packages before their release, and the +[PyPI](https://pypi.python.org/pypi) repository, where you can make your +releases. You need to register a username and password with both these sites. +The username and passwords for both these sites need not be the same. To upload +your package through the command line, you need to store your username and +password in a file called `.pypirc` in your `$HOME` directory with the +following format. + +```shell +[distutils] +index-servers = + pypi + pypitest + +[pypi] +repository=https://pypi.python.org/pypi +username= +password= + +[pypitest] +repository=https://testpypi.python.org/pypi +username= +password= +``` +Make sure that all details in `setup.py` are up to date. To upload your package +to the Test server, execute: +``` +python setup.py register -r pypitest +python setup.py sdist upload -r pypitest +``` +Your package should now be visible on: https://testpypi.python.org/pypi + +To install a package from the test server, execute: +``` +pip install -i https://testpypi.python.org/pypi +``` + +Similary, to upload your package to the PyPI server execute +``` +python setup.py register -r pypi +python setup.py sdist upload -r pypi +``` +To install your package, execute: +``` +pip install +``` + +*Thank you for cleanly contributing to the scikit-learn ecosystem!* diff --git a/ci_scripts/install.sh b/ci_scripts/install.sh new file mode 100644 index 0000000..057a004 --- /dev/null +++ b/ci_scripts/install.sh @@ -0,0 +1,40 @@ +# Deactivate the travis-provided virtual environment and setup a +# conda-based environment instead +deactivate + +# Use the miniconda installer for faster download / install of conda +# itself +pushd . +cd +mkdir -p download +cd download +echo "Cached in $HOME/download :" +ls -l +echo +if [[ ! -f miniconda.sh ]] + then + wget http://repo.continuum.io/miniconda/Miniconda-3.6.0-Linux-x86_64.sh \ + -O miniconda.sh + fi +chmod +x miniconda.sh && ./miniconda.sh -b +cd .. +export PATH=/home/travis/miniconda/bin:$PATH +conda update --yes conda +popd + +# Configure the conda environment and put it in the path using the +# provided versions +conda create -n testenv --yes python=$PYTHON_VERSION pip nose \ + numpy=$NUMPY_VERSION scipy=$SCIPY_VERSION cython=$CYTHON_VERSION + matplotlib +source activate testenv + + +if [[ "$COVERAGE" == "true" ]]; then + pip install coverage coveralls +fi + +python --version +python -c "import numpy; print('numpy %s' % numpy.__version__)" +python -c "import scipy; print('scipy %s' % scipy.__version__)" +python setup.py develop \ No newline at end of file diff --git a/ci_scripts/push_doc.sh b/ci_scripts/push_doc.sh new file mode 100644 index 0000000..e60bd8f --- /dev/null +++ b/ci_scripts/push_doc.sh @@ -0,0 +1,49 @@ +#!/bin/bash +# This script is meant to be called in the "deploy" step defined in +# circle.yml. See https://circleci.com/docs/ for more details. +# The behavior of the script is controlled by environment variable defined +# in the circle.yml in the top level folder of the project. + +MSG="Pushing the docs for revision for branch: $CIRCLE_BRANCH, commit $CIRCLE_SHA1" + +cd $HOME +# Copy the build docs to a temporary folder +rm -rf tmp +mkdir tmp +cp -R $HOME/$DOC_REPO/doc/_build/html/* ./tmp/ + +# Clone the docs repo if it isnt already there +if [ ! -d $DOC_REPO ]; + then git clone "git@github.com:$USERNAME/"$DOC_REPO".git"; +fi + +cd $DOC_REPO +git branch gh-pages +git checkout -f gh-pages +git reset --hard origin/gh-pages +git clean -dfx + +for name in $(ls -A $HOME/$DOC_REPO); do + echo "Filename = $name" + case $name in + .nojekyll) + ;; + circle.yml) + ;; + *) + git rm -rf $name + ;; + esac +done + +# Copy the new build docs +mkdir $DOC_URL +cp -R $HOME/tmp/* ./$DOC_URL/ + +git config --global user.email $EMAIL +git config --global user.name $USERNAME +git add -f ./$DOC_URL/ +git commit -m "$MSG" +git push -f origin gh-pages + +echo $MSG diff --git a/ci_scripts/success.sh b/ci_scripts/success.sh new file mode 100644 index 0000000..043da74 --- /dev/null +++ b/ci_scripts/success.sh @@ -0,0 +1,13 @@ +set -e + +if [[ "$COVERAGE" == "true" ]]; then + # Need to run coveralls from a git checkout, so we copy .coverage + # from TEST_DIR where nosetests has been run + cp $TEST_DIR/.coverage $TRAVIS_BUILD_DIR + cd $TRAVIS_BUILD_DIR + # Ignore coveralls failures as the coveralls server is not + # very reliable but we don't want travis to report a failure + # in the github UI just because the coverage report failed to + # be published. + coveralls || echo "Coveralls upload failed" +fi \ No newline at end of file diff --git a/ci_scripts/test.sh b/ci_scripts/test.sh new file mode 100644 index 0000000..3867571 --- /dev/null +++ b/ci_scripts/test.sh @@ -0,0 +1,13 @@ +set -e + +# Get into a temp directory to run test from the installed scikit learn and +# check if we do not leave artifacts +mkdir -p $TEST_DIR + +cd $TEST_DIR + +if [[ "$COVERAGE" == "true" ]]; then + nosetests -s --with-coverage --cover-package=$MODULE $MODULE +else + nosetests -s $MODULE +fi diff --git a/circle.yml b/circle.yml new file mode 100644 index 0000000..0425a2d --- /dev/null +++ b/circle.yml @@ -0,0 +1,56 @@ +machine: + environment: + # The github organization or username of the repository which hosts the + # project and documentation. + USERNAME: "scikit-learn-contrib" + + # The repository where the documentation will be hosted + DOC_REPO: "project-template" + + # The base URL for the Github page where the documentation will be hosted + DOC_URL: "" + + # The email is to be used for commits in the Github Page + EMAIL: "vnb222+ci@nyu.edu" + +dependencies: + + # Various dependencies + pre: + - sudo -E apt-get -yq remove texlive-binaries --purge + - sudo apt-get update + - sudo apt-get install libatlas-dev libatlas3gf-base + - sudo apt-get install build-essential python-dev python-setuptools + # install numpy first as it is a compile time dependency for other packages + - pip install --upgrade numpy + - pip install --upgrade scipy matplotlib setuptools nose coverage sphinx pillow sphinx-gallery + # Installing required packages for `make -C doc check command` to work. + - sudo -E apt-get -yq update + - sudo -E apt-get -yq --no-install-suggests --no-install-recommends --force-yes install dvipng texlive-latex-base texlive-latex-extra + - pip install --upgrade cython numpydoc + - pip install --upgrade scikit-learn + + # The --user is needed to let sphinx see the source and the binaries + # The pipefail is requested to propagate exit code + override: + - python setup.py clean + - python setup.py develop + - set -o pipefail && cd doc && make html 2>&1 | tee ~/log.txt +test: + # Grep error on the documentation + override: + - cat ~/log.txt && if grep -q "Traceback (most recent call last):" ~/log.txt; then false; else true; fi +deployment: + push: + branch: master + commands: + - bash ci_scripts/push_doc.sh +general: + # Open the doc to the API + artifacts: + - "doc/_build/html" + - "~/log.txt" + # Restric the build to the branch master only + branches: + only: + - master \ No newline at end of file diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..508376e --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,184 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + -rm -rf auto_examples/ + -rm -rf generated/* + -rm -rf modules/generated/* + +html: + # These two lines make the build a bit more lengthy, and the + # the embedding of images more robust + rm -rf $(BUILDDIR)/html/_images + #rm -rf _build/doctrees/ + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/project-template.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/project-template.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/project-template" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/project-template" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/doc/api.rst b/doc/api.rst new file mode 100644 index 0000000..78014d6 --- /dev/null +++ b/doc/api.rst @@ -0,0 +1,4 @@ +API Documentation +================= + +* :doc:`template` \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..103adf9 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,302 @@ +# -*- coding: utf-8 -*- +# +# project-template documentation build configuration file, created by +# sphinx-quickstart on Mon Jan 18 14:44:12 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration --------------------------------------------------- + +# Try to override the matplotlib configuration as early as possible +try: + import gen_rst +except: + pass +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'numpydoc', + 'sphinx.ext.pngmath', + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', + 'sphinx_gallery.gen_gallery' + +] + +sphinx_gallery_conf = { + # path to your examples scripts + 'examples_dirs' : '../examples', + # path where to save gallery generated examples + 'gallery_dirs' : 'auto_examples'} + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# Generate the plots for the gallery +plot_gallery = True + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'sklearn-template' +copyright = u'2016, Vighnesh Birodkar' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.1' +# The full version, including alpha/beta/rc tags. +release = '0.1.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'nature' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'project-templatedoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'project-template.tex', u'project-template Documentation', + u'Vighnesh Birodkar', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'project-template', u'project-template Documentation', + [u'Vighnesh Birodkar'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'project-template', u'project-template Documentation', + u'Vighnesh Birodkar', 'project-template', 'One line description of project.', + 'Miscellaneous'), +] + +def generate_example_rst(app, what, name, obj, options, lines): + # generate empty examples files, so that we don't get + # inclusion errors if there are no examples for a class / module + examples_path = os.path.join(app.srcdir, "modules", "generated", + "%s.examples" % name) + if not os.path.exists(examples_path): + # touch file + open(examples_path, 'w').close() + + +def setup(app): + app.connect('autodoc-process-docstring', generate_example_rst) + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..fd17c82 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,31 @@ +.. project-template documentation master file, created by + sphinx-quickstart on Mon Jan 18 14:44:12 2016. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to sklearn-template's documentation! +============================================ + +This project is a reference implementation to anyone who wishes to develop +scikit-learn compatible classes. It comes with a `template` module which +contains a single estimator with unit tests. + + + .. toctree:: + :maxdepth: 2 + + api + auto_examples/index + ... + +See the `README `_ +for more information. + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..79c1e19 --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,242 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\project-template.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\project-template.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +:end diff --git a/doc/template.rst b/doc/template.rst new file mode 100644 index 0000000..f385b51 --- /dev/null +++ b/doc/template.rst @@ -0,0 +1,7 @@ +Template +======== + +The documentation of the template module. + +.. automodule:: skltemplate.template + :members: \ No newline at end of file diff --git a/examples/README.txt b/examples/README.txt new file mode 100644 index 0000000..a5d244b --- /dev/null +++ b/examples/README.txt @@ -0,0 +1,6 @@ +.. _general_examples: + +General examples +================ + +Introductory examples. diff --git a/examples/plot_template.py b/examples/plot_template.py new file mode 100644 index 0000000..5df665a --- /dev/null +++ b/examples/plot_template.py @@ -0,0 +1,17 @@ +""" +=========================== +Plotting Template Estimator +=========================== + +An example plot of TemplateEstimator +""" +import numpy as np +from skltemplate import TemplateEstimator +from matplotlib import pyplot as plt + +X = np.arange(100).reshape(100, 1) +y = np.zeros((100, )) +estimator = TemplateEstimator() +estimator.fit(X, y) +plt.plot(estimator.predict(X)) +plt.show() \ No newline at end of file diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..4026cc7 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +nose>=1.1.2 +scikit-learn>=0.17 diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..224a779 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,2 @@ +[metadata] +description-file = README.md \ No newline at end of file diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..2ff8d92 --- /dev/null +++ b/setup.py @@ -0,0 +1,28 @@ +from __future__ import print_function +import sys +from setuptools import setup, find_packages + +with open('requirements.txt') as f: + INSTALL_REQUIRES = [l.strip() for l in f.readlines() if l] + + +try: + import numpy +except ImportError: + print('numpy is required during installation') + sys.exit(1) + +try: + import scipy +except ImportError: + print('scipy is required during installation') + sys.exit(1) + +setup(name='sklearn-template', + version='0.0.3', + description='A template for scikit-learn compatible packages', + author='Vighnesh Birodkar', + packages=find_packages(), + install_requires=INSTALL_REQUIRES, + author_email='vighneshbirodkar@nyu.edu', + ) diff --git a/skltemplate/__init__.py b/skltemplate/__init__.py new file mode 100644 index 0000000..0505eba --- /dev/null +++ b/skltemplate/__init__.py @@ -0,0 +1,4 @@ +from .template import TemplateEstimator +from . import template + +__all__ = ['TemplateEstimator', 'template'] \ No newline at end of file diff --git a/skltemplate/template.py b/skltemplate/template.py new file mode 100644 index 0000000..f71e1fb --- /dev/null +++ b/skltemplate/template.py @@ -0,0 +1,50 @@ +""" +This is a module to be used as a reference for building other modules +""" +from sklearn.base import BaseEstimator +from sklearn.utils import check_X_y, check_array + +class TemplateEstimator(BaseEstimator): + """ A template estimator to be used as a reference implementation . + + Parameters + ---------- + demo_param : str, optional + A parameter used for demonstation of how to pass and store paramters. + """ + def __init__(self, demo_param='demo_param'): + self.demo_param = 'demo_param' + + def fit(self, X, y): + """A reference implementation of a fitting function + + Parameters + ---------- + X : array-like or sparse matrix of shape = [n_samples, n_features] + The training input samples. + y : array-like, shape = [n_samples] or [n_samples, n_outputs] + The target values (class labels in classification, real numbers in + regression). + Returns + ------- + self : object + Returns self. + """ + X, y = check_X_y(X, y) + return self + + def predict(self, X): + """ A reference implementation of a predicting function. + + Parameters + ---------- + X : array-like of shape = [n_samples, n_features] + The input samples. + + Returns + ------- + y : array of shape = [n_samples] + Returns :math:`x^2` where :math:`x` is the first column of `X`. + """ + X = check_array(X) + return X[:, 0]**2 \ No newline at end of file diff --git a/skltemplate/tests/test_common.py b/skltemplate/tests/test_common.py new file mode 100644 index 0000000..1b7aa12 --- /dev/null +++ b/skltemplate/tests/test_common.py @@ -0,0 +1,5 @@ +from sklearn.utils.estimator_checks import check_estimator +from skltemplate import TemplateEstimator + +def test_common(): + return check_estimator(TemplateEstimator) diff --git a/skltemplate/tests/test_template.py b/skltemplate/tests/test_template.py new file mode 100644 index 0000000..ac066d2 --- /dev/null +++ b/skltemplate/tests/test_template.py @@ -0,0 +1,11 @@ +import numpy as np +from numpy.testing import assert_almost_equal + +from skltemplate import TemplateEstimator + + +def test_demo(): + X = np.random.random((100, 10)) + estimator = TemplateEstimator() + estimator.fit(X, X[:, 0]) + assert_almost_equal(estimator.predict(X), X[:, 0]**2) \ No newline at end of file