Add tutorials page to docs (#238)

stefmolin · Nov 6, 2024 · 0e892a5 · 0e892a5
1 parent 4ce9e99
commit 0e892a5
Show file tree

Hide file tree

Showing 16 changed files with 58 additions and 18 deletions.
diff --git a/README.md b/README.md
@@ -161,8 +161,8 @@ In this example, we morphed the built-in panda `Dataset` into the star `Shape`.
 Data Morph is intended to be used as a teaching tool to illustrate the importance of data visualization. Here are some potential classroom activities for instructors:
 
 - **Statistics Focus**: Have students pick one of the [built-in datasets](https://stefaniemolin.com/data-morph/stable/api/data_morph.data.loader.html#data_morph.data.loader.DataLoader), and morph it into all available [target shapes](https://stefaniemolin.com/data-morph/stable/api/data_morph.shapes.factory.html#data_morph.shapes.factory.ShapeFactory). Ask students to comment on which transformations worked best and why.
-- **Creativity Focus**: Have students [create a new dataset](https://stefaniemolin.com/data-morph/stable/custom_datasets.html) (*e.g.*, your school logo or something that the student designs), and morph that into multiple [target shapes](https://stefaniemolin.com/data-morph/stable/api/data_morph.shapes.factory.html#data_morph.shapes.factory.ShapeFactory). Ask students to comment on which transformations worked best and why.
-- **Math and Coding Focus**: Have students [create a custom shape](https://stefaniemolin.com/data-morph/dev/shape_creation.html) by inheriting from `LineCollection` or `PointCollection`, and try morphing a couple of the [built-in datasets](https://stefaniemolin.com/data-morph/stable/api/data_morph.data.loader.html#data_morph.data.loader.DataLoader) into that shape. Ask students to explain how they chose to calculate the shape, and comment on which transformations worked best and why.
+- **Creativity Focus**: Have students [create a new dataset](https://stefaniemolin.com/data-morph/dev/custom-datasets.html) (*e.g.*, your school logo or something that the student designs), and morph that into multiple [target shapes](https://stefaniemolin.com/data-morph/stable/api/data_morph.shapes.factory.html#data_morph.shapes.factory.ShapeFactory). Ask students to comment on which transformations worked best and why.
+- **Math and Coding Focus**: Have students [create a custom shape](https://stefaniemolin.com/data-morph/dev/shape-creation.html) by inheriting from `LineCollection` or `PointCollection`, and try morphing a couple of the [built-in datasets](https://stefaniemolin.com/data-morph/stable/api/data_morph.data.loader.html#data_morph.data.loader.DataLoader) into that shape. Ask students to explain how they chose to calculate the shape, and comment on which transformations worked best and why.
 
 If you end up using Data Morph in your classroom, I would love to hear about it. Please [send me a message](https://stefaniemolin.com/contact/) detailing how you used it and how it went.
 

diff --git a/docs/_static/tutorials/dataset-creation.jpg b/docs/_static/tutorials/dataset-creation.jpg
diff --git a/docs/_static/easter-egg-to-wide-lines.gif → ...ic/tutorials/easter-egg-to-wide-lines.gif b/docs/_static/easter-egg-to-wide-lines.gif → ...ic/tutorials/easter-egg-to-wide-lines.gif
diff --git a/docs/_static/tutorials/example-shapes.png b/docs/_static/tutorials/example-shapes.png
diff --git a/docs/_static/shapes_uml.svg → docs/_static/tutorials/shapes_uml.svg b/docs/_static/shapes_uml.svg → docs/_static/tutorials/shapes_uml.svg
diff --git a/docs/_static/tutorials/style.css b/docs/_static/tutorials/style.css
@@ -0,0 +1,4 @@
+.tutorial-card-image {
+    height: 225px;
+    object-fit: cover;
+}
diff --git a/docs/classroom-ideas.rst b/docs/classroom-ideas.rst
@@ -9,11 +9,11 @@ of data visualization. Here are some potential classroom activities for instruct
   and morph it into all available `target shapes
   <./api/data_morph.shapes.factory.html#data_morph.shapes.factory.ShapeFactory>`_.
   Ask students to comment on which transformations worked best and why.
-* **Creativity Focus**: Have students :doc:`create a new dataset <custom_datasets>`
+* **Creativity Focus**: Have students :doc:`create a new dataset <tutorials/custom-datasets>`
   (*e.g.*, your school logo or something that the student designs), and morph that into multiple
   `target shapes <./api/data_morph.shapes.factory.html#data_morph.shapes.factory.ShapeFactory>`_.
   Ask students to comment on which transformations worked best and why.
-* **Math and Coding Focus**: Have students :doc:`create a custom shape <shape_creation>`
+* **Math and Coding Focus**: Have students :doc:`create a custom shape <tutorials/shape-creation>`
   by inheriting from :class:`.LineCollection` or :class:`.PointCollection`, and try morphing a
   couple of the `built-in datasets <./api/data_morph.data.loader.html#data_morph.data.loader.DataLoader>`_
   into that shape. Ask students to explain how they chose to calculate the shape, and

diff --git a/docs/conf.py b/docs/conf.py
@@ -42,6 +42,7 @@
     'sphinx_copybutton',
     'sphinx_argparse_cli',
     'matplotlib.sphinxext.plot_directive',
+    'sphinx_design',
 ]
 
 templates_path = ['_templates']
@@ -100,6 +101,7 @@
 
 html_theme = 'pydata_sphinx_theme'
 html_static_path = ['_static']
+html_css_files = ['tutorials/style.css']
 html_logo = '_static/logo.png'
 html_favicon = '_static/favicon.ico'
 
@@ -130,6 +132,7 @@
     'analytics': {
         'google_analytics_id': 'G-FMNM78QSKK',
     },
+    'show_prev_next': False,
 }
 
 html_context = {
@@ -144,10 +147,9 @@
 # https://github.com/pydata/pydata-sphinx-theme/pull/1682
 html_sidebars = {
     'cli': [],
-    'custom_datasets': [],
     'quickstart': [],
-    'release_notes': [],
-    'shape_creation': [],
+    'release-notes': [],
+    'tutorials/*': [],
 }
 
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -7,11 +7,10 @@ Data Morph
    :hidden:
 
    quickstart
-   custom_datasets
-   shape_creation
+   tutorials/index
    cli
    api
-   release_notes
+   release-notes
 
 .. automodule:: data_morph
    :noindex:

diff --git a/docs/quickstart.rst b/docs/quickstart.rst
@@ -141,5 +141,5 @@ out the other built-in options:
 * The :attr:`.ShapeFactory.AVAILABLE_SHAPES` attribute contains a list of available shapes, which
   are also visualized in the :class:`.ShapeFactory` documentation.
 
-For further customization, the :doc:`custom_datasets` tutorial discusses how to generate custom input datasets,
-and the :doc:`shape_creation` tutorial discusses how to generate custom target shapes.
+For further customization, the :doc:`tutorials/custom-datasets` tutorial discusses how to generate custom
+input datasets, and the :doc:`tutorials/shape-creation` tutorial discusses how to generate custom target shapes.
diff --git a/docs/release_notes.rst → docs/release-notes.rst b/docs/release_notes.rst → docs/release-notes.rst
@@ -13,7 +13,7 @@ What's New
 * Made it possible to install via ``conda``.
 * Configured versioned documentation hosted in GitHub Pages.
 * Generated a :doc:`CLI reference <cli>` page in the documentation.
-* Provided a :doc:`custom dataset creation tutorial <custom_datasets>` to the documentation.
+* Provided a :doc:`custom dataset creation tutorial <tutorials/custom-datasets>` to the documentation.
 * Included logo and badges in README.
 * Included an example using easing for the animation to the documentation.
 * Included reference to `article on the creation of Data Morph

diff --git a/docs/custom_datasets.rst → docs/tutorials/custom-datasets.rst b/docs/custom_datasets.rst → docs/tutorials/custom-datasets.rst
@@ -17,7 +17,7 @@ Generate points
 Below are some ways to create an original starter dataset. Each method will
 yield some (x, y) points, which may be in web browser coordinates or Cartesian
 coordinates. Save these to a text file called ``points.txt`` for processing in the
-:ref:`next step <custom_datasets:create a csv file in cartesian coordinates>`.
+:ref:`next step <tutorials/custom-datasets:create a csv file in cartesian coordinates>`.
 
 .. note::
     All tools included in this section are for reference only;
@@ -103,7 +103,7 @@ Pass the path to the CSV file to use those points as the starting shape:
 
 Here is an example animation generated from a custom dataset:
 
-.. figure:: _static/easter-egg-to-wide-lines.gif
+.. figure:: ../_static/tutorials/easter-egg-to-wide-lines.gif
    :alt: Congratulations, you've found the Easter egg!
    :align: center
 

diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst
@@ -0,0 +1,33 @@
+*********
+Tutorials
+*********
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   custom-datasets
+   shape-creation
+
+.. grid:: 1 1 2 2
+    :gutter: 5
+
+    .. grid-item-card:: Design and use a custom dataset
+        :link-type: doc
+        :link: custom-datasets
+        :link-alt: Custom datasets tutorial
+        :img-bottom: ../_static/tutorials/dataset-creation.jpg
+        :img-alt: Custom dataset of Easter bunny with egg.
+        :class-img-bottom: tutorial-card-image
+
+        Learn how to make a custom dataset in this tutorial.
+
+    .. grid-item-card:: Create your own target shape
+        :link-type: doc
+        :link: shape-creation
+        :link-alt: Shape creation tutorial
+        :img-bottom: ../_static/tutorials/example-shapes.png
+        :img-alt: Example target shapes in Data Morph.
+        :class-img-bottom: tutorial-card-image
+
+        Learn how to add a new target shape in this tutorial.
diff --git a/docs/shape_creation.rst → docs/tutorials/shape-creation.rst b/docs/shape_creation.rst → docs/tutorials/shape-creation.rst
@@ -27,7 +27,7 @@ base class (:class:`.Shape`), which defines the basics of how a shape
 needs to behave (*i.e.*, it must have a ``distance()`` method and a
 ``plot()`` method).
 
-.. figure:: _static/shapes_uml.svg
+.. figure:: ../_static/tutorials/shapes_uml.svg
    :alt: UML diagram showing the hierarchy of the shape classes.
    :align: center
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -62,6 +62,7 @@ optional-dependencies.docs = [
   "sphinx>=7.2.6",
   "sphinx-argparse-cli>=1.16.0",
   "sphinx-copybutton>=0.5.1",
+  "sphinx-design>=0.6.1",
 ]
 urls."Bug Tracker" = "https://github.com/stefmolin/data-morph/issues"
 urls."Documentation" = "https://stefaniemolin.com/data-morph/stable/api.html"
@@ -110,7 +111,7 @@ lint.ignore = [
   "ANN101", # missing type annotation for self (will be removed in future ruff version)
   "ANN102", # missing type annotation for cls in classmethod (will be removed in future ruff version)
   "E501",   # line-too-long
-  "TRY003", # avoid specifying long messages outside the exception class (revisit later and consider making custom acceptions)
+  "TRY003", # avoid specifying long messages outside the exception class (revisit later and consider making custom exceptions)
 ]
 
 lint.extend-per-file-ignores."docs/*" = [

diff --git a/src/data_morph/__init__.py b/src/data_morph/__init__.py
@@ -4,7 +4,8 @@
 Morph an input dataset of 2D points into select shapes, while preserving the summary
 statistics to a given number of decimal points through simulated annealing. It is intended
 to be used as a teaching tool to illustrate the importance of data visualization (see
-`Data Morph in the classroom`_ for ideas).
+`Data Morph in the classroom <https://stefaniemolin.com/data-morph/dev/index.html#data-morph-in-the-classroom>`_
+for ideas).
 
 Notes
 -----