- 'proplot/tests/**'

[diff "ipynb"]

textconv = nbstripout -t

[filter "nbstripout"]

clean = "f() { echo >&2 \"clean: nbstripout $1\"; nbstripout; }; f %f"

smudge = "f() { echo >&2 \"smudge: cat $1\"; cat; }; f %f"

required = true

**/tests/*.ipynb

version: 2

sphinx:

builder: html

configuration: docs/conf.py

build:

image: latest

python:

version: 3.6

conda:

environment: docs/environment.yml

sudo: false # use container based build

language: python

notifications:

email: false

python:

- "3.6"

before_install:

- wget http://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh

- bash miniconda.sh -b -p $HOME/miniconda

- export PATH="$HOME/miniconda/bin:$PATH"

- hash -r

- conda config --set always_yes yes --set changeps1 no --set show_channel_urls true

- conda update -q conda

- conda info -a

install:

- conda env create -n proplot-dev --file docs/environment.yml

- source activate proplot-dev

- conda install pip

- conda list

- which conda

- which python

- pip install .

- python setup.py install --user

script:

- pushd docs

- make html

- popd

Changelog history

ProPlot v1.0

First official release (ETA: Spring 2020) after which we will start broadcasting this project more loudly. We will bump to this version when some major refactoring tasks have been completed.

ProPlot v0.1

This will be the first version when ProPlot is released on pypi. Changes thereafter will be listed here. Think of the v0 releases as "beta versions".

Contribution guide

Contributions are highly welcomed and appreciated. Every little help counts,

so do not hesitate! You can make a high impact on ProPlot just by using it and

reporting `issues <https://github.com/lukelbd/proplot/issues>`__.

The following sections cover some general guidelines

regarding development in ProPlot for maintainers and contributors.

Nothing here is set in stone and can't be changed.

Feel free to suggest improvements or changes in the workflow.

Feature requests and feedback

We are eager to hear about your requests for new features and any suggestions about the

API, infrastructure, and so on. Feel free to submit these as

`issues <https://github.com/lukelbd/proplot/issues/new>`__ with the label "feature."

Please make sure to explain in detail how the feature should work and keep the scope as

narrow as possible. This will make it easier to implement in small PRs.

Report bugs

Report bugs for ProPlot in the `issue tracker <https://github.com/lukelbd/proplot/issues>`__

with the label "bug".

If you are reporting a bug, please include:

* Your operating system name and version.

* Any details about your local setup that might be helpful in troubleshooting,

specifically the Python interpreter version, installed libraries, and ProPlot

version.

* Detailed steps to reproduce the bug.

If you can write a demonstration test that currently fails but *should* pass,

that is a very useful commit to make as well, even if you cannot fix the bug itself.

Fix bugs

Look through the `GitHub issues for bugs <https://github.com/lukelbd/proplot/labels/bug>`__.

Talk to developers to find out how you can fix specific bugs.

Write documentation

ProPlot could always use better documentation. For small changes, you can edit documentation files directly in the GitHub web interface,

without using a local copy.

* The documentation is written in reStructuredText with `numpydoc <https://numpydoc.readthedocs.io/en/latest/>`__ style headers.

* The `default ReST role <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-default_role>`__ is ``'py:obj'``. This is meant to encourage populating docstrings with links to the API reference. ProPlot uses `intersphinx <http://www.sphinx-doc.org/en/stable/ext/intersphinx.html>`__, so you can also link to sphinx documentation from other projects, e.g. matplotlib. In general, you should compress your links with a tilde, e.g. ``~path.to.function``.

* When editing the ipython notebooks found in ``docs``, make sure to put your example descriptions inside reStructedText cells, not markdown cells. This lets us populate the descriptions with sphinx links. See `this guide <https://nbsphinx.readthedocs.io/en/0.4.3/raw-cells.html#Usage>`__ for how to convert cells to ReST.

Some helpful ReST guides are located `here <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`__ and `here <https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst>`__.

.. note::

To build the documentation locally, use the following commands:

.. code:: bash

The built documentation should be available in the ``docs/_build/html``.

Preparing pull requests

#. Fork the

`proplot GitHub repository <https://github.com/lukelbd/proplot>`__. It's

fine to use ProPlot as your fork repository name because it will live

under your user.

#. Clone your fork locally using `git <https://git-scm.com/>`__, connect your repository

to the upstream (main project), and create a branch:

.. code-block:: bash

If you need some help with git, follow the

`quick start guide <https://git.wiki.kernel.org/index.php/QuickStart>`__.

#. If you intend to make changes / add examples to the ipython notebooks,

you need to install and configure

`nbstripout <https://github.com/kynan/nbstripout>`__ with

.. code-block:: bash

This strips notebook cell output when files are staged, which reduces the

repo storage size and lets us use

`nbsphinx <https://nbsphinx.readthedocs.io/en/0.4.3/>`__

to test each ``git push``, since ``nbsphinx`` must then re-run every cell.

The ``git config`` command associates the filters declared in

``proplot/.gitattributes`` with the operations described in ``proplot/.gitconfig``

by adding them to the *recognized* local configuration file

``proplot/.git/config``.

#. Make an editable install of ProPlot by running:

.. code-block:: bash

This way when you ``import proplot``, your

local copy is used. Make sure matplotlib is already installed.

#. Break your edits up into reasonably sized commits.

.. code-block:: bash

The commit messages should be short, sweet, and use the imperative mood,

e.g. "Fix bug" instead of "Fixed bug".

#. Create a new changelog entry in ``CHANGELOG.rst``:

- The entry should be entered as:

.. code-block::

where ``<description>`` is the description of the PR related to the change, ``<PR number>`` is the pull request number, and ``<author name>`` is your first and last name.

- Add yourself to list of authors at the end of ``CHANGELOG.rst`` file if not there yet, in alphabetical order.

#. Finally, submit a pull request through the GitHub website using this data:

.. code-block::

Note that you can create the Pull Request while you're working on this. The PR will update

as you add more commits. ProPlot developers and contributors can then review your code

and offer suggestions.

Release procedure

ProPlot will follow semantic versioning, e.g. v1.0.0. A major version causes incompatible

API changes, a minor version adds functionality, and a patch covers bug fixes.

#. Create a new branch ``release-vX.x.x`` with the version for the release.

#. Update ``CHANGELOG.rst``, and make sure all new changes, features are reflected in the documentation.

#. Open a new pull request for this branch targeting ``master``.

#. After all tests pass and the PR has been approved, merge the PR into ``master``.

#. Pull down the new version of master:

.. code-block:: bash

#. Tag a release and push to github:

.. code-block:: bash

#. Build and publish release on PyPI:

.. code-block:: bash

Installation

This package is a work-in-progress -- currently, there is no formal release

on PyPi (ETA: January 2020). For the time being, you may install directly from Github using:

.. code-block:: bash

To upgrade to the latest version, run ``pip uninstall proplot``, then re-install.

The dependencies are `matplotlib <https://matplotlib.org/>`__ and `numpy <http://www.numpy.org/>`__. The optional geographic mapping features require `cartopy <https://scitools.org.uk/cartopy/docs/latest/>`__ and/or `basemap <https://matplotlib.org/basemap/index.html>`__.