Add RTD Documentation (#35)

Also:

* Move tabulate records code to standalone functions (fixes #27)
* Move `get_cache`  to top level and `cli/utils.py` to `utils.py` (improves access and fixes #29)
* Create .readthedocs.yml
* Add PyPi deployment

.circleci/config.yml

@@ -0,0 +1,38 @@
+version: 2
+jobs:
+  build_docs:
+    docker:
+      - image: circleci/python:3.6-stretch
+    steps:
+      # Get our data and merge with upstream
+      - run: sudo apt-get update
+      - checkout
+
+      - restore_cache:
+          keys:
+            - cache-pip
+      - run: |
+          pip install --user -e .[rtd]
+          pip install -r docs/requirements.txt
+      - save_cache:
+          key: cache-pip
+          paths:
+            - ~/.cache/pip
+
+      # Build the docs
+      - run:
+          name: Build docs to store
+          command: |
+            cd docs
+            make html-strict
+
+      - store_artifacts:
+          path: docs/_build/html/
+          destination: html
+
+
+workflows:
+  version: 2
+  default:
+    jobs:
+      - build_docs

.github/ISSUE_TEMPLATE/documentation-improvements.md

@@ -0,0 +1,14 @@
+---
+name: Documentation Improvements
+about: Suggest improvements to the documentation
+title: ''
+labels: documentation
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. This section is unclear [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.

.readthedocs.yml

@@ -0,0 +1,10 @@
+version: 2
+
+python:
+  version: 3
+  install:
+      - method: pip
+        path: .
+        extra_requirements:
+          - rtd
+      - requirements: docs/requirements.txt

.travis.yml

@@ -4,13 +4,10 @@ matrix:
     include:
       - python: 3.7
         env: TEST_TYPE="pre-commit"
-      # Not working with some of the annotation syntax
-      # - python: 3.5
-      #   env: TEST_TYPE="pytest"
       - python: 3.6
         env: TEST_TYPE="pytest"
       - python: 3.7
-        env: TEST_TYPE="pytest"
+        env: TEST_TYPE="pytest" PYPI_DEPLOY=true
       - python: 3.8
         env: TEST_TYPE="pytest"
 install:
@@ -38,3 +35,13 @@ after_success:
   if [[ "$TEST_TYPE" == "pytest" ]]; then
       coveralls
   fi
+
+deploy:
+  - provider: pypi
+    distributions: "sdist bdist_wheel"
+    user: cjsewell
+    password:
+      secure: sTAhmXxRw3QdL9WS33dxEXaJVJSIk208X35/3tSQycLLBk/VAgHTTPGeOKBnZ8dY18iwMpALrmI9FX7QhCVLBI5RO7U4AkrjFtVnWtvyKPaC1OBUDYh4OKCyUlBhHx2ko3HdH/bQwjE57/TgbgC7cjIRnEIMGrLnL3623imnpr+/86jL9rsachEjoN6pswaHYkPwAChDOWUWpJeYkH06HgQy9AOHkuJNDvTho/RWNGv3lCT8rbvAjLfgQgUCoxl1iQOrL/FTLj2mt4FIk8I2203Kra9KeFXkz2X32R/sWHFOkB++5KoYB41r4J4lCzU2cBhgucrIwIrO3QW3Kw44CYbzK5q+BjbXnazNu7H6sqN7SjCjwr+E3ib17mjcB87cTgwCqxQeiRrX4GMqngC/xsXPgK6XdhQzihpyKKzNpS5BK/XtvANldzsYvYPKyPAbbWqnpwb2+aEAq00a2gUTCg5ZmWiEm8Pu8jRp2OG9C5Uk1ymP7ZCcL0NDCoSSKRC8oOTx1ERQjL4xN/rNk85ZXu5lME0cGrWU9ZRxOYi/GFJAzGD2Fi52D1oO1BgxXM3hMI1HB1xiMwRTbmxOMbnFz2Ewzi/RAzGtslCg9iLbqphjAbkGyOzkZDhptEn2eOx+ThcFP9sW4cOocrPcySSjKFfrtJWaWDNUBX+nkcAFsDY=
+    on:
+      tags: true
+      condition: $PYPI_DEPLOY = true

.vscode/settings.json

@@ -1,7 +1,7 @@
 {
     "files.exclude": {
         "**/.git": true,
-        "**/.github": true,
+        "**/.github": false,
         "**/.svn": true,
         "**/.hg": true,
         "**/CVS": true,

README.md

@@ -2,8 +2,11 @@
 
 # jupyter-cache
 
-[![Build Status](https://travis-ci.org/ExecutableBookProject/jupyter-cache.svg?branch=master)](https://travis-ci.org/ExecutableBookProject/jupyter-cache)
-[![Coverage Status](https://coveralls.io/repos/github/ExecutableBookProject/jupyter-cache/badge.svg?branch=master)](https://coveralls.io/github/ExecutableBookProject/jupyter-cache?branch=master)
+[![CI Status][travis-badge]][travis-link]
+[![Coverage][coveralls-badge]][coveralls-link]
+[![Documentation Status][rtd-badge]][rtd-link]
+[![Code style: black][black-badge]][black-link]
+[![PyPI][pypi-badge]][pypi-link]
 
 A defined interface for working with a cache of jupyter notebooks.
 
@@ -20,10 +23,21 @@ Some desired requirements (not yet all implemented):
 - Store execution artifacts: created during exeution
 - A transparent and robust cache invalidation: imagine the user updating an external dependency or a Python module, or checking out a different git branch.
 
+[travis-badge]: https://travis-ci.org/ExecutableBookProject/jupyter-cache.svg?branch=master
+[travis-link]: https://travis-ci.org/ExecutableBookProject/jupyter-cache
+[coveralls-badge]: https://coveralls.io/repos/github/ExecutableBookProject/jupyter-cache/badge.svg?branch=master
+[coveralls-link]: https://coveralls.io/github/ExecutableBookProject/jupyter-cache?branch=master
+[rtd-badge]: https://readthedocs.org/projects/jupyter-cache/badge/?version=latest
+[rtd-link]: https://jupyter-cache.readthedocs.io/en/latest/?badge=latest
+[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
+[pypi-badge]: https://img.shields.io/pypi/v/jupyter-cache.svg
+[pypi-link]: https://pypi.org/project/jupyter-cache
+[black-link]: https://github.com/ambv/black
+
 ## Install
 
 ```bash
-pip install -e "git+https://github.com/ExecutableBookProject/jupyter-cache.git#egg=jupyter-cache[cli]"
+pip install jupyter-cache[cli]
 ```
 
 For development:

docs/.gitignore

@@ -0,0 +1,2 @@
+_build/
+_api/

docs/Makefile

@@ -0,0 +1,27 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# raise warnings to errors
+html-strict:
+	@$(SPHINXBUILD) -b html -nW --keep-going "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
+clean:
+	rm -r $(BUILDDIR)

docs/conf.py

@@ -0,0 +1,82 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# 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.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "Jupyter Cache"
+copyright = "2020, Executable Book Project"
+author = "Executable Book Project"
+
+master_doc = "index"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "myst_parser",
+    "myst_nb",
+    "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
+    # "sphinx.ext.autodoc",
+    # "sphinx.ext.viewcode",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "**/example_nbs/*",
+    "**/.jupyter_cache/**/*",
+]
+
+
+# -- 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 = "pandas_sphinx_theme"
+html_logo = "_static/logo.jpg"
+
+# 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"]
+
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3.7", None)}
+autodoc_member_order = "bysource"
+
+nitpick_ignore = [
+    ("py:class", "Any"),
+    ("py:class", "Tuple"),
+    ("py:class", "ForwardRef"),
+    ("py:class", "NoneType"),
+]
+
+
+def setup(app):
+    """Add functions to the Sphinx setup."""
+    # app.connect("builder-inited", run_apidoc)

docs/develop/contributing.md

@@ -0,0 +1,79 @@
+# Contributing
+
+[![CI Status][travis-badge]][travis-link]
+[![Coverage][coveralls-badge]][coveralls-link]
+[![Code style: black][black-badge]][black-link]
+[![CircleCI][circleci-badge]][circleci-link]
+[![Documentation Status][rtd-badge]][rtd-link]
+
+## Code Style
+
+Code style is tested using [flake8](http://flake8.pycqa.org),
+with the configuration set in `.flake8`,
+and code formatted with [black](https://github.com/ambv/black).
+
+Installing with `jupyter-cache[code_style]` makes the [pre-commit](https://pre-commit.com/)
+package available, which will ensure this style is met before commits are submitted, by reformatting the code
+and testing for lint errors.
+It can be setup by:
+
+```shell
+>> cd jupyter-cache
+>> pre-commit install
+```
+
+Optionally you can run `black` and `flake8` separately:
+
+```shell
+>> black .
+>> flake8 .
+```
+
+Editors like VS Code also have automatic code reformat utilities, which can adhere to this standard.
+
+All functions and class methods should be annotated with types and include a docstring. The prefered docstring format is outlined in `jupyter-cache/docstring.fmt.mustache` and can be used automatically with the
+[autodocstring] VS Code extension.
+
+## Testing
+
+For code tests:
+
+```shell
+>> cd jupyter-cache
+>> pytest
+```
+
+For documentation build tests:
+
+```shell
+>> cd jupyter-cache/docs
+>> make clean
+>> make html-strict
+```
+
+## Pull Requests
+
+To contribute, make Pull Requests to the `master` branch (this is the default branch). A PR can consist of one or multiple commits. Before you open a PR, make sure to clean up your commit history and create the commits that you think best divide up the total work as outlined above (use `git rebase` and `git commit --amend`). Ensure all commit messages clearly summarise the changes in the header and the problem that this commit is solving in the body.
+
+Merging pull requests: There are three ways of 'merging' pull requests on GitHub:
+
+- Squash and merge: take all commits, squash them into a single one and put it on top of the base branch.
+    Choose this for pull requests that address a single issue and are well represented by a single commit.
+    Make sure to clean the commit message (title & body)
+- Rebase and merge: take all commits and 'recreate' them on top of the base branch. All commits will be recreated with new hashes.
+    Choose this for pull requests that require more than a single commit.
+    Examples: PRs that contain multiple commits with individually significant changes; PRs that have commits from different authors (squashing commits would remove attribution)
+- Merge with merge commit: put all commits as they are on the base branch, with a merge commit on top
+    Choose for collaborative PRs with many commits. Here, the merge commit provides actual benefits.
+
+[travis-badge]: https://travis-ci.org/ExecutableBookProject/jupyter-cache.svg?branch=master
+[travis-link]: https://travis-ci.org/ExecutableBookProject/jupyter-cache
+[coveralls-badge]: https://coveralls.io/repos/github/ExecutableBookProject/jupyter-cache/badge.svg?branch=master
+[coveralls-link]: https://coveralls.io/github/ExecutableBookProject/jupyter-cache?branch=master
+[circleci-badge]: https://circleci.com/gh/ExecutableBookProject/jupyter-cache.svg?style=shield
+[circleci-link]: https://circleci.com/gh/ExecutableBookProject/jupyter-cache
+[rtd-badge]: https://readthedocs.org/projects/jupyter-cache/badge/?version=latest
+[rtd-link]: https://jupyter-cache.readthedocs.io/en/latest/?badge=latest
+[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
+[black-link]: https://github.com/ambv/black
+[autodocstring]: https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring

docs/index.md

@@ -0,0 +1,58 @@
+# Jupyter Cache
+
+A defined interface for working with a cache of jupyter notebooks.
+
+```{warning}
+This project is in an alpha state. It may evolve rapidly and/or make breaking changes!
+Comments, requests, or bugreports are welcome and recommended! Please
+[open an issue here](https://github.com/ExecutableBookProject/jupyter-cache/issues)
+```
+
+This packages provides a clear [API](use/api) and [CLI](use/cli) for staging, executing and cacheing
+Jupyter Notebooks. Although there are certainly other use cases,
+the principle use case this was written for is generating books / websites,
+created from multiple notebooks (and other text documents),
+during which it is desired that notebooks can be *auto-executed* **only**
+if the notebook had been modified in a way that may alter its code cell outputs.
+
+Some desired requirements (not yet all implemented):
+
+- A clear and robust API
+- The cache is persistent on disk
+- Notebook comparisons separate out "edits to content" from "edits to code cells".
+  Cell rearranges and code cell changes should require a re-execution.
+  Text content changes should not.
+- Allow parallel access to notebooks (for execution)
+- Store execution statistics/reports.
+- Store external assets: Notebooks being executed often require external assets: importing scripts/data/etc. These are prepared by the users.
+- Store execution artifacts: created during exeution
+- A transparent and robust cache invalidation: imagine the user updating an external dependency or a Python module, or checking out a different git branch.
+
+## Installation
+
+To install `jupytes-cache`, do the following:
+
+```bash
+pip install jupyter-cache[cli]
+```
+
+For package development:
+
+```bash
+git clone https://github.com/ExecutableBookProject/jupyter-cache
+cd jupyter-cache
+git checkout develop
+pip install -e .[cli,code_style,testing,rtd]
+```
+
+Here are the site contents:
+
+```{toctree}
+---
+maxdepth: 2
+caption: Contents
+---
+using/cli.md
+using/api.ipynb
+develop/contributing.md
+```

docs/requirements.txt

@@ -0,0 +1 @@
+git+https://github.com/pandas-dev/pandas-sphinx-theme.git@master