Package: grafter
Copyright (c) 2019, Bonsai teamAll rights reserved.Redistribution and use in source and binary forms, with or withoutmodification, are permitted provided that the following conditions are met:* Redistributions of source code must retain the above copyright notice, thislist 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 documentationand/or other materials provided with the distribution.* Neither the name of the copyright holder nor the names of itscontributors may be used to endorse or promote products derived fromthis 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, THEIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AREDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLEFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIALDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS ORSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVERCAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USEOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.Description: # python-skeletonSkeleton for Python projects that meet BONSAI guidelines.Under development, follows the following:* https://github.com/pyscaffold/pyscaffold* https://docs.python-guide.org/writing/structure/* https://github.com/modocache/pyhoe## Getting startedThe first step is to choose your library name. You should check [pypi](https://pypi.org/) to make sure your name is still available! Names should be lower case, and use underscores (`_`), not hyphens (`-`).## LicenseThe default license is 3-clause BSD. You need to insert your name(s) in the `LICENSE` file.## Basic setupRename the directory `your_library_name` to the *exact* name of your library.### Update `setup.py`* Change every instance of `your_library_name` to the name of your library.* Change `author`, `author_email`, `url`, and the PyPI [classifiers](https://pypi.org/pypi?%3Aaction=list_classifiers).### requirements.txtAdd any python libraries which are requirements for your library to be used## ExecutableThere is a skeleton executable using [docopt](http://docopt.org/) in `your_library_name/bin`.If you want to have a command line program that you can call from a terminal, you will need to do the following:* Rename the file `your_library_name/bin/rename_me_cli.py`* Change the `entry_points` section in `setup.py` to match the new directory and file namesOtherwise, do the following:* Delete the `bin` directory* Remove `docopt` from `requirements.txt`* Delete the `entry_points` section from `setup.py`.## DocumentationWe recommend building documentation using [sphinx](http://www.sphinx-doc.org/en/master/), and hosting documentation on [Github pages](https://pages.github.com/) or [read the docs](https://readthedocs.org/). Github pages is easier to configure, while read the docs will build automatically with each pushed commit.To start the documentation structure, first install `sphinx` using conda or pip. Then change to the `docs` directory, and run `sphinx-quickstart`. We suggest the following **non-default** configuration values (otherwise the default is fine):* autodoc: automatically insert docstrings from modules (y/n): `y`* mathjax: include math, rendered in the browser by MathJax (y/n): `y`* githubpages: create .nojekyll file to publish the document on GitHub pages (y/n): `y` if using Github pagesNote that the default format for writing code is [RestructuredText](http://docutils.sourceforge.net/rst.html), which is different than markdown (what is used in Github, and this readme). You can use [markdown with sphinx](https://www.sphinx-doc.org/en/master/usage/markdown.html).There are other options for documenting code; the two most popular being [Asciidoctor](https://asciidoctor.org/) and [MkDocs](https://www.mkdocs.org/).## TestingWriting good tests is a learned art. People also have strong opinions on what makes good tests! Read some tutorials, learn about fixtures, try things out. Write unit tests, write integration tests, try TDD or BDD. Some tests are better than no tests, but no tests may be better than bad tests. 100% coverage is a journey, not a destination.## Code quality checksWe strongly recommend using [pytest](https://docs.pytest.org/en/latest/) for testing. It is installable via conda or pip.### pylama[pylama](https://github.com/klen/pylama) is a collection of code quality checks which is easy to use. Just install via conda or pip, and then run `pylama <your_library_name>`. You can also run pylama on your tests with `pytest --pylama`.## Continuous integration (CI)The services listed here should already have permission to work with BONSAMURAIS repositories. If you are working on you own account, you will have to give permission for each service to read from GitHub. Don't worry, it is pretty simple, and there are normally good instructions.CI testing requires that you have already written tests.### CoverallsLog in to https://coveralls.io/ with your GitHub account. Click on `Add Repos`, find your repository, and click on the slider button.### Travis (Linux and MacOs)Edit the file `.travis.yml`, and change following:* `<add your conda dependencies here>`: Change this is a list of your conda dependencies, separated by spaces* `<add any other dependencies not available in conda here>`: Change this to a list of dependencies not in conda, or delete this line* `<your_library_name>`: Change as in `setup.py`Edit the file `ci/requirements-travis.txt`, and copy everything from `requirements.txt` (but leave the testing libraries).Log in using your GitHub account, and add the repository you want to test. Travis will now run on every pushed commit, and send coverage information to coveralls.### Appveyor (Windows)Edit the file `.appveyor.yml`, and change following:* `<add your conda dependencies here>`: Change this is a list of your conda dependencies, separated by spaces* `<add any other dependencies not available in conda here>`: Change this to a list of dependencies not in conda, or delete this lineLog in using your GitHub account, and add the repository you want to test. Then, click on settings, and change the `Custom configuration .yml file name` to `.appveyor.yml`. Appveyor will now run on every pushed commit.## Conda `dev` package automatic uploadsThis section describes how to set up `travis` to upload a development version of your library every time the CI tests run. If you don't want this, then please delete the following section from `.travis.yml`:if [ "$TRAVIS_BRANCH" = "master" -a "$TRAVIS_PULL_REQUEST" = "false" ]; thenconda install conda-build anaconda-client conda-verify;bash ci/conda_upload.sh;fiOtherwise, please do the following. This instructions are based off a [helpful gist](https://gist.github.com/zshaheen/fe76d1507839ed6fbfbccef6b9c13ed9):* Create an account on anaconda.org.* Create an access token. Go to `settings` > `access`, and check "Allow write access to the API site" and "Allow read access to the API site". Then give your token a name like "changethis-dev-upload" (the name doesn't matter, choose something that you will recognize in six months), and generate the token. Copy the generated string somewhere safe (DON'T share this).* Log in to travis, click on your library, and then go to `more options` >  `settings`, and scroll down to "environment variables". Enter the variable "CONDA_UPLOAD_TOKEN" with the token you just generated.* Change every field in `ci/meta.yaml`, `ci/macos-requirements.txt`, and `ci/conda_upload.sh` that has a `<>`.## Upload to `pypi`After you have set everything up, you can already upload a `0.0.1` version. You will need a [pypi account first](https://pypi.org/) ([store your account credentials](https://docs.python.org/3.7/distutils/packageindex.html#pypirc)). This is a good idea for two reasons: You will reserve your awesome project name, and you make your project more visible - outside collaborators might surprise you by just showing up! To upload to pypi, you should install [twine](https://github.com/pypa/twine) via the usual channels. Then, in your library directory (i.e. the one where `setup.py` is), run `python setup.py sdist bdist_wheel` and `twine upload dist/my_awesome_stuff*.*`.## Releasing a new versionVersions should follow the [semantic versioning standard](Semantic Versioning](https://semver.org/spec/v2.0.0.html). To release a new version, you should add a description of the changes to the `CHANGELOG.md`, then change the version number in both `setup.py` and `<my_library>/__init__.py`. You can then create the distribution and upload it as before with `python setup.py` and `twine`.Platform: UNKNOWNClassifier: Intended Audience :: End Users/DesktopClassifier: Intended Audience :: DevelopersClassifier: Intended Audience :: Science/ResearchClassifier: License :: OSI Approved :: BSD LicenseClassifier: Operating System :: MacOS :: MacOS XClassifier: Operating System :: Microsoft :: WindowsClassifier: Operating System :: POSIXClassifier: Programming Language :: PythonClassifier: Programming Language :: Python :: 3Classifier: Programming Language :: Python :: 3.5Classifier: Programming Language :: Python :: 3.6Classifier: Programming Language :: Python :: 3.7Classifier: Topic :: Scientific/Engineering :: Information AnalysisClassifier: Topic :: Scientific/Engineering :: MathematicsClassifier: Topic :: Scientific/Engineering :: Visualization