Organize documentation and sync ipython notebooks instead of nbconvert-generated RST files

.codacy.yaml → .codacy.yml

@@ -1,8 +1,8 @@
 ---
 exclude_paths:
   - 'docs/**'
+  - 'proplot/tests/**'
   - 'proplot/fonts/**'
   - 'proplot/colors/**'
   - 'proplot/cycles/**'
   - 'proplot/cmaps/**'
-  - 'proplot/cmaps_rejects/**'

.gitattributes

@@ -1,6 +1,3 @@
-# Strips notebook output for diffs and when staging files
-# Download with 'pip install nbstripout'
 # See: https://github.com/kynan/nbstripout
 *.ipynb filter=nbstripout
 *.ipynb diff=ipynb
-

.gitconfig

@@ -0,0 +1,7 @@
+# See: https://github.com/kynan/nbstripout
+[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

.gitignore

@@ -6,31 +6,29 @@
 # PyPi stuff
 build
 dist
+.eggs
 *.egg-info
 
-# Builds made during testing
+# Local docs builds
 docs/api
 docs/_build
 
-# Deleted
-trash
-notebooks*
-garbage
+# Notebook stuff
+**/tests/*.ipynb
+.ipynb_checkpoints
 
 # Python extras
 *.log
 *.pyc
 .*.pyc
 __pycache__
 
-# Notebooks
-# NOTE: For now ignore, contributors just need RST files to build docs and
-# have personal control over quickstart.
-*.ipynb
-.ipynb_checkpoints
-
 # OS files
 .DS_Store
 .DS_Store?
 ._*
 .Trashes
+
+# Old files
+trash
+garbage

.readthedocs.yml

@@ -0,0 +1,16 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+version: 2
+
+# Sphinx config
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+
+# Python config
+build:
+  image: latest
+python:
+  version: 3.6
+conda:
+  environment: docs/environment.yml

.travis.yml

@@ -0,0 +1,37 @@
+# Travis Continuos Integration
+# Currently only tests notebook files
+# Based on http://conda.pydata.org/docs/travis.html
+# Not sure why pip install . is necessary since conf.py adds it
+# to the the path. Maybe nbsphinx executes in separate environment.
+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.rst

@@ -1,10 +1,14 @@
 =================
-Changelog History
+Changelog history
 =================
 
-ProPlot v1.0.0
-==============
-First official release. Coming soon! Future changes and releases will be documented.
+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".
 
 Internals/Minor Fixes
 ---------------------

HOWTOCONTRIBUTE.rst

@@ -0,0 +1,200 @@
+==================
+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
+
+        cd docs
+        pip install requirements.txt
+        make html
+
+    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
+
+      git clone git@github.com:YOUR_GITHUB_USERNAME/proplot.git
+      cd proplot
+      git remote add upstream git@github.com:lukelbd/proplot.git
+      git checkout -b your-bugfix-feature-branch-name master
+
+   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
+
+      cd proplot
+      pip install nbstripout
+      git config --local include.path ../.gitconfig
+
+   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
+
+      pip install -e .
+
+   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
+
+      git commit -a -m "<commit message>"
+      git push -u
+
+   The commit messages should be short, sweet, and use the imperative mood,
+   e.g. "Fix bug" instead of "Fixed bug".
+
+   ..
+      #. Run all the tests. Now running tests is as simple as issuing this command:
+         .. code-block:: bash
+            coverage run --source proplot -m py.test
+         This command will run tests via the ``pytest`` tool against Python 3.7.
+
+#. Create a new changelog entry in ``CHANGELOG.rst``:
+
+   - The entry should be entered as:
+
+      .. code-block::
+
+         <description> (:pr:`<PR number>`) `<author name>`_
+
+    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::
+
+      head-fork: YOUR_GITHUB_USERNAME/proplot
+      compare: your-branch-name
+
+      base-fork: lukelbd/proplot
+      base: master
+
+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
+
+      git checkout master
+      git pull
+
+#. Tag a release and push to github:
+
+   .. code-block:: bash
+
+      git tag -a v1.0.0 -m "Version 1.0.0"
+      git push origin master --tags
+
+#. Build and publish release on PyPI:
+
+   .. code-block:: bash
+
+    git clean -xfd # remove files not checked into git
+    python setup.py sdist bdist_wheel --universal # build package
+    twine upload dist/* # register and push to pypi
+

INSTALL.rst

@@ -0,0 +1,14 @@
+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
+
+   pip install git+https://github.com/lukelbd/proplot.git
+
+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>`__.
+