Merge pull request #37 from dhhagan/dhhagan-feature-docs

Add auto-deploy for docs and enhance docs

docs/Makefile

@@ -3,18 +3,49 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html notebooks
+
 # Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  clean      to remove generated output"
+	@echo "  html       to make standalone HTML files"
+	@echo "  notebooks  to make the Jupyter notebook-based tutorials"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+	-rm -rf example_thumbs/*
+	-rm -rf examples/*
+	-rm -rf generated/*
+	-$(MAKE) -C _tutorial clean
+
+. PHONY: tutorials
+tutorials:
+	@mkdir -p tutorial
+	@$(MAKE) -C _tutorial
+
+notebooks: tutorials
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+# .PHONY: help Makefile
 
-.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)
 
-# 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)
+# notebooks: tutorials

docs/_static/copybutton.js

@@ -0,0 +1,59 @@
+// originally taken from scikit-learn's Sphinx theme
+$(document).ready(function() {
+    /* Add a [>>>] button on the top-right corner of code samples to hide
+     * the >>> and ... prompts and the output and thus make the code
+     * copyable.
+     * Note: This JS snippet was taken from the official python.org
+     * documentation site.*/
+    var div = $('.highlight-python .highlight,' +
+                '.highlight-python3 .highlight,' +
+                '.highlight-pycon .highlight')
+    var pre = div.find('pre');
+
+    // get the styles from the current theme
+    pre.parent().parent().css('position', 'relative');
+    var hide_text = 'Hide the prompts and output';
+    var show_text = 'Show the prompts and output';
+    var border_width = pre.css('border-top-width');
+    var border_style = pre.css('border-top-style');
+    var border_color = pre.css('border-top-color');
+    var button_styles = {
+        'cursor':'pointer', 'position': 'absolute', 'top': '0', 'right': '0',
+        'border-color': border_color, 'border-style': border_style,
+        'border-width': border_width, 'color': border_color, 'text-size': '75%',
+        'font-family': 'monospace', 'padding-left': '0.2em', 'padding-right': '0.2em'
+    }
+
+    // create and add the button to all the code blocks that contain >>>
+    div.each(function(index) {
+        var jthis = $(this);
+        if (jthis.find('.gp').length > 0) {
+            var button = $('<span class="copybutton">&gt;&gt;&gt;</span>');
+            button.css(button_styles)
+            button.attr('title', hide_text);
+            jthis.prepend(button);
+        }
+        // tracebacks (.gt) contain bare text elements that need to be
+        // wrapped in a span to work with .nextUntil() (see later)
+        jthis.find('pre:has(.gt)').contents().filter(function() {
+            return ((this.nodeType == 3) && (this.data.trim().length > 0));
+        }).wrap('<span>');
+    });
+
+    // define the behavior of the button when it's clicked
+    $('.copybutton').toggle(
+        function() {
+            var button = $(this);
+            button.parent().find('.go, .gp, .gt').hide();
+            button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'hidden');
+            button.css('text-decoration', 'line-through');
+            button.attr('title', show_text);
+        },
+        function() {
+            var button = $(this);
+            button.parent().find('.go, .gp, .gt').show();
+            button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'visible');
+            button.css('text-decoration', 'none');
+            button.attr('title', hide_text);
+        });
+});

docs/_static/css/custom.css

@@ -0,0 +1,113 @@
+/**** Overriding theme defaults ****/
+
+html[data-theme=light]{
+    --pst-color-primary: rgb(52, 54, 99);
+    --pst-color-secondary: rgb(107, 161, 174);
+    --pst-color-link: rgb(74, 105, 145);
+    --pst-color-inline-code: rgb(96, 141, 130);
+  }
+
+  :root {
+    --pst-font-size-h1: 38px;
+    --pst-font-size-h2: 32px;
+    --pst-font-size-h3: 27px;
+    --pst-font-size-h4: 22px;
+    --pst-font-size-h5: 18px;
+    --pst-font-size-h6: 15px;
+
+  }
+
+  /* Syntax highlighting */
+
+  /* string literals */
+  html[data-theme=light] .highlight .s2 {
+    color: rgb(74, 105, 145);
+    font-weight: normal;
+  }
+  /* number literals */
+  html[data-theme=light] .highlight .mi {
+    color: rgb(136, 97, 153);
+    font-weight: normal;
+  }
+  html[data-theme=light] .highlight .mf {
+    color: rgb(136, 97, 153);
+    font-weight: normal;
+  }
+  /* operators */
+  html[data-theme=light] .highlight .o {
+    color: rgb(219, 164, 117);
+    font-weight: bold;
+  }
+  /* builtins */
+  html[data-theme=light] .highlight .kc {
+    color: rgb(107, 161, 174);
+    font-weight: bold;
+  }
+
+  /* Use full page width without sidebars */
+  .bd-content {
+    max-width: 100%;
+    flex-grow: 1;
+  }
+
+  /* Function signature customization */
+  dt {
+    font-weight: 500;
+    color: rgb(52, 54, 99);
+  }
+
+  span.default_value {
+    color: rgb(124, 141, 138);
+  }
+
+  /* highlight over function signature after link */
+  dt:target, span.highlighted {
+    background-color: #fdebba;
+  }
+
+  /* *********************************************************************** */
+
+  /* --- Badges for categorizing release notes --- */
+
+  .label,
+  .badge {
+    display: inline-block;
+    padding: 2px 4px;
+    font-size: 11.844px;
+    /* font-weight: bold; */
+    line-height: 13px;
+    color: #ffffff;
+    vertical-align: baseline;
+    white-space: nowrap;
+    /* text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.25); */
+    background-color: #999999;
+  }
+  .badge {
+    padding-left: 9px;
+    padding-right: 9px;
+    -webkit-border-radius: 9px;
+    -moz-border-radius: 9px;
+    border-radius: 9px;
+    opacity: 70%;
+  }
+  .badge-api {
+    background-color: #c44e52;
+  }
+  .badge-defaults {
+    background-color: #dd8452;
+  }
+  .badge-docs {
+    background-color: #8172b3;
+  }
+  .badge-feature {
+    background-color: #55a868;
+  }
+  .badge-enhancement {
+    background-color: #4c72b0;
+  }
+  .badge-fix {
+      background-color: #ccb974;
+  }
+  .badge-build {
+      background-color: #937860;
+  }

docs/_tutorial/Makefile

@@ -0,0 +1,10 @@
+rst_files := $(patsubst %.ipynb,../tutorial/%.rst,$(wildcard *.ipynb))
+export MPLBACKEND := module://matplotlib_inline.backend_inline
+
+tutorial: ${rst_files}
+
+../tutorial/%.rst: %.ipynb
+	../tools/nb_to_doc.py $*.ipynb ../tutorial
+
+clean:
+	rm -rf ../tutorial

docs/api.rst

@@ -0,0 +1,60 @@
+.. _api_ref:
+
+API Reference
+=============
+
+.. currentmodule:: atmospy
+
+.. _style_api:
+
+Themeing
+--------
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    set_theme
+
+Utility Functions
+-----------------
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    load_dataset
+    get_dataset_names
+
+.. _function_api:
+
+Plotting Functions
+------------------
+
+Regression Plots
+~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    regplot
+
+Trend Plots
+~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    calendarplot
+    dielplot
+
+Source Attribution Plots
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: generated/
+    :nosignatures:
+
+    pollutionroseplot