revisit examples (#79)

* clean up dev & user envs * update readme * revisit quick look * revisit collaboration and review * revisit logging basics * fix header links to GitHub * fix warning * revisit logging training metadata * revisit visualizing logged dataframes * revisit logging asynchronously * revisit logging concurrently * revisit git integration * revisit prefect integration * revisit scikit-learn integration * add dashboard pic to quick look * update references to moved environment file * update environment filepath in workflow * address feedback
capitalone · Apr 19, 2021 · 7c1a4cc · 7c1a4cc
1 parent 86278a9
commit 7c1a4cc
Show file tree

Hide file tree

Showing 34 changed files with 4,085 additions and 1,219 deletions.
diff --git a/.github/workflows/test-package.yml b/.github/workflows/test-package.yml
@@ -30,7 +30,7 @@ jobs:
         channels: conda-forge
         channel-priority: true  
         activate-environment: rubicon-dev
-        environment-file: ci/environment.yml
+        environment-file: environment.yml
     - name: Check formatting with black
       run: |
         black --check .

diff --git a/.gitignore b/.gitignore
@@ -1,8 +1,8 @@
 __pycache__
 docs/build
-docs/source/*.ipynb
-docs/source/out
-docs/source/data
+docs/source/**/*.ipynb
+docs/source/**/*.png
+docs/source/**/data
 .coverage
 .coverage.*
 .cache/**

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -3,15 +3,13 @@ repos:
         rev: 20.8b1
         hooks:
         - id: black
-          language_version: python3.7
 
     -   repo: https://github.com/timothycrosley/isort
-        rev: 5.7.0
+        rev: 5.8.0
         hooks:
         - id: isort
-          args: ["-rc"]
 
     - repo: https://gitlab.com/pycqa/flake8
-      rev: 3.8.4
+      rev: 3.9.0
       hooks:
           - id: flake8
diff --git a/README.md b/README.md
@@ -110,7 +110,7 @@ Then use conda to setup a development environment:
 
 ```bash
 conda create -n rubicon-dev python=3.8
-conda env update -f ci/environment.yml -n rubicon-dev
+conda env update -f environment.yml -n rubicon-dev
 conda activate rubicon-dev
 ```
 

diff --git a/ci/match_version.sh b/ci/match_version.sh
diff --git a/docs/Makefile b/docs/Makefile
@@ -17,21 +17,32 @@ html: prepare
 # Clear the examples directory and then copy the advanced example 
 # notebooks to the source folder so nbsphinx can build docs off of them
 prepare:
-	rm -rf ./source/rubicon-root ./source/*.ipynb
-	rm -rf ./source/data
-
-	cp ../notebooks/logging-examples/logging-basics.ipynb ./source
-	cp ../notebooks/logging-examples/logging-asynchronously.ipynb ./source
-	cp ../notebooks/logging-examples/logging-concurrently.ipynb ./source
-	cp ../notebooks/logging-examples/logging-training-metadata.ipynb ./source
-	cp ../notebooks/logging-examples/visualizing-logged-dataframes.ipynb ./source
-	cp ../notebooks/integrations/integration-git.ipynb ./source
-	cp ../notebooks/integrations/integration-prefect-workflows.ipynb ./source
-	cp ../notebooks/integrations/integration-sklearn.ipynb ./source
+	rm -rf ./source/rubicon-root
+
+	rm -rf ./source/logging-examples
+	rm -rf ./source/integrations
+	rm ./source/*.ipynb
+
+	mkdir ./source/logging-examples
+	mkdir ./source/logging-examples/data
+	mkdir ./source/integrations
+
+	cp ../notebooks/quick-look.ipynb ./source
+	cp ../notebooks/logging-examples/logging-basics.ipynb ./source/logging-examples
+	cp ../notebooks/logging-examples/logging-asynchronously.ipynb ./source/logging-examples
+	cp ../notebooks/logging-examples/logging-concurrently.ipynb ./source/logging-examples
+	cp ../notebooks/logging-examples/logging-training-metadata.ipynb ./source/logging-examples
+	cp ../notebooks/logging-examples/visualizing-logged-dataframes.ipynb ./source/logging-examples
+	cp ../notebooks/integrations/integration-git.ipynb ./source/integrations
+	cp ../notebooks/integrations/integration-prefect-workflows.ipynb ./source/integrations
+	cp ../notebooks/integrations/integration-sklearn.ipynb ./source/integrations
 
 	# some notebooks require sample data
-	mkdir ./source/data
-	cp ../notebooks/logging-examples/data/revenue_data.csv ./source/data
+	cp ../notebooks/logging-examples/data/revenue_data.csv ./source/logging-examples/data
+
+	# some notebooks have images
+	cp ../notebooks/quick-look-dashboard.png ./source
+	cp ../notebooks/integrations/integration-git-dashboard.png ./source/integrations
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
@@ -12,6 +12,18 @@
     }
 }
 
+@media (prefers-color-scheme: dark) {
+    tr:nth-child(odd) {
+	background-color: #202020 !important;
+    }
+}
+
+@media (prefers-color-scheme: dark) {
+    .dataframe {
+	color: white !important;
+    }
+}
+
 .hidden {
     display: none;
 }
@@ -31,3 +43,7 @@
 #Visualizing-Logged-Dataframes .admonition.warning {
     display: none;
 }
+
+div.output_area.stderr {
+    display: none;
+}
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -48,6 +48,8 @@
 # See: https://nbsphinx.readthedocs.io/en/0.2.15/never-execute.html#Explicitly-Dis-/
 nbsphinx_execute = "never"
 nbsphinx_prolog = """
+|
+
 `View this notebook on GitHub <https://github.com/capitalone/rubicon/tree/main/notebooks/{{ env.doc2path(env.docname, base=None) }}>`_
 
 ----

diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -24,11 +24,11 @@ Creating a Development Environment
 ==================================
 
 We have a ``conda`` environment YAML file with all the necessary dependencies
-in the ``ci`` directory.
+at the root of the repository.
 
 .. code-block:: shell
 
-   conda env create -f ci/environment.yml
+   conda env create -f environment.yml
 
 Building ``rubicon``
 ====================
@@ -37,7 +37,7 @@ After you've cloned the repository, use ``pip`` to install ``rubicon`` locally:
 
 .. code-block:: shell
 
-   python -m pip install -e .
+   python -m pip install -e .[all]
 
 Style
 =====

diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -11,15 +11,15 @@ Basics
 .. toctree::
    :maxdepth: 1
 
-   logging-basics
-   logging-training-metadata
-   visualizing-logged-dataframes
+   logging-examples/logging-basics
+   logging-examples/logging-training-metadata
+   logging-examples/visualizing-logged-dataframes
 
 Advanced
 --------
 
 .. toctree::
    :maxdepth: 1
 
-   logging-asynchronously
-   logging-concurrently
+   logging-examples/logging-asynchronously
+   logging-examples/logging-concurrently
diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
@@ -89,7 +89,10 @@ A **dataframe** is logged to a **project** or an **experiment**.
 
   import pandas as pd
 
-  confusion_matrix = pd.DataFrame([[5, 0, 0], [0, 5, 1], [0, 0, 4]], columns=["x", "y", "z"])
+  confusion_matrix = pd.DataFrame(
+      [[5, 0, 0], [0, 5, 1], [0, 0, 4]],
+      columns=["x", "y", "z"],
+  )
   experiment.log_dataframe(confusion_matrix)
 
 Artifact (:ref:`rubicon.Artifact<library-reference-artifact>`)

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -15,6 +15,8 @@ reproducibility for both developers and stakeholders alike. While experimenting,
 the Rubicon dashboard makes it easy to explore, filter, visualize, and share
 recorded work.
 
+Visit the :ref:`Glossary<glossary>` to explore Rubicon's terminology.
+
 Components
 ==========
 
@@ -28,6 +30,8 @@ Rubicon is composed of three parts:
 * And a process for sharing a selected subset of logged data with collaborators
   or reviewers that leverages intake_
 
+To see each of these parts in action, visit the `Quick Look`_!
+
 Workflow
 ========
 
@@ -45,17 +49,12 @@ When the model is ready for review, Rubicon makes it easy to share specific
 subsets of the data with model reviewers and stakeholders, giving them the
 context necessary for a complete model review and approval.
 
----
-
-Visit the :ref:`glossary<glossary>` to explore Rubicon's terminology. And to see Rubicon
-in action, visit the :ref:`quick look<quick-look>`!
-
 .. toctree::
    :maxdepth: 2
    :hidden:
    :caption: Getting Started:
 
-   quick_look.rst
+   quick-look
    glossary.rst
    install.rst
 
@@ -83,3 +82,4 @@ in action, visit the :ref:`quick look<quick-look>`!
 .. _fsspec: https://filesystem-spec.readthedocs.io/en/latest/?badge=latest
 .. _dash: https://dash.plotly.com/
 .. _intake: https://intake.readthedocs.io/en/latest/
+.. _Quick Look: ./quick-look.html
diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -28,17 +28,13 @@ Extras
 ``rubicon`` has a few optional extras if you're installing with ``pip`` (these extras are all
 installed by default when using ``conda``).
 
-|
-
 The ``ui`` extra installs the requirements necessary for using ``rubicon``'s visualization tools.
-For a preview, take a look at the **dashboard** section of the :ref:`quick look<quick-look>`.
+For a preview, take a look at the :ref:`dashboard<dashboard>` section of the docs.
 
 .. code-block:: console
 
     pip install rubicon-ml[ui]
 
-|
-
 The ``prefect`` extra installs the requirements necessary for using the `Prefect <https://prefect.io>`_ 
 tasks in the ``rubicon.workflow`` module. Take a look at the **Prefect integration** :ref:`example<examples>` 
 to see ``rubicon`` integrated into a simple Prefect flow.
@@ -47,8 +43,6 @@ to see ``rubicon`` integrated into a simple Prefect flow.
 
     pip install rubicon-ml[prefect]
 
-|
-
 To install all extra modules, use the ``all`` extra.
 
 .. code-block:: console

diff --git a/docs/source/integrations.rst b/docs/source/integrations.rst
@@ -13,6 +13,6 @@ Supported Integrations
 .. toctree::
    :maxdepth: 1
 
-   integration-git
-   integration-prefect-workflows
-   integration-sklearn
+   integrations/integration-git
+   integrations/integration-prefect-workflows
+   integrations/integration-sklearn