Fix #44: add version and examples to library docs (#46)

dsa-ou · Aug 28, 2024 · 8dfad0b · 8dfad0b
1 parent e6ec031
commit 8dfad0b
Show file tree

Hide file tree

Showing 9 changed files with 49 additions and 43 deletions.
diff --git a/README.md b/README.md
@@ -45,7 +45,7 @@ When a new version of the library is to be put on PyPI:
 1. Run again the notebooks (including the coding guide), to test the library.
 2. Update the [changelog](CHANGELOG.md).
 3. Re-generate the docs as explained above.
-4. Bump the version in `pyproject.toml` and `Deepnote/Dockerfile`,
+4. Bump the version in `pyproject.toml`, `src/docs/library.md` and `Deepnote/Dockerfile`,
    so that a new docker image can be built.
 5. Commit with a tag indicating the new version.
 6. Run `poetry build` and `poetry publish`.

diff --git a/docs/library/index.html b/docs/library/index.html
@@ -1058,7 +1058,8 @@
 
 
 <h1 id="library">Library</h1>
-<p>The <code>algoesup</code> library provides support for testing, timing and linting code.</p>
+<p>The <code>algoesup</code> library provides support for testing, timing and linting code.
+This documentation is for version 0.3.1.</p>
 <h2 id="testing">Testing</h2>
 
 
@@ -1069,7 +1070,7 @@ <h2 id="testing">Testing</h2>
 
   <div class="doc doc-contents first">
 
-      <p>Simplified testing for Python functions</p>
+      <p>Simplified testing for Python functions, see the <a href="../coding/#testing">examples</a>.</p>
 
 
 
@@ -1166,7 +1167,7 @@ <h3 id="algoesup.test.test" class="doc doc-heading">
 
   <div class="doc doc-contents first">
 
-      <p>Tools for measuring and plotting run-times</p>
+      <p>Tools for measuring and plotting run-times, see the <a href="../coding/#performance-analysis">examples</a>.</p>
 
 
 
@@ -1204,8 +1205,8 @@ <h3 id="algoesup.time.time_functions" class="doc doc-heading">
   <div class="doc doc-contents ">
 
       <p>Print or plot the run-times of different functions for the same inputs.</p>
-<p><code>time_functions</code> prints or plots the run-times given list of functions and an input 
-generator. Inputs are generated based on a starting size and are doubled a specified 
+<p><code>time_functions</code> prints or plots the run-times given list of functions and an input
+generator. Inputs are generated based on a starting size and are doubled a specified
 number of times.</p>
 
 
@@ -1374,8 +1375,8 @@ <h3 id="algoesup.time.time_cases" class="doc doc-heading">
   <div class="doc doc-contents ">
 
       <p>Print or plot the run-times of <code>function</code> for different input cases.</p>
-<p><code>time_cases</code> prints or plots the run-times of a single function using a list of 
-different input generators. Inputs are generated based on a starting size and are 
+<p><code>time_cases</code> prints or plots the run-times of a single function using a list of
+different input generators. Inputs are generated based on a starting size and are
 doubled a specified number of times.</p>
 
 
@@ -1615,7 +1616,7 @@ <h3 id="algoesup.time.time_functions_int" class="doc doc-heading">
           </td>
           <td>
             <div class="doc-md-description">
-              <p>If True, print the run-times in text format. </p>
+              <p>If True, print the run-times in text format.</p>
             </div>
           </td>
           <td>
@@ -1659,7 +1660,8 @@ <h3 id="algoesup.time.time_functions_int" class="doc doc-heading">
 
   <div class="doc doc-contents first">
 
-      <p>Linting tools for Jupyter Notebook environments</p>
+      <p>Linting tools for Jupyter Notebook environments.</p>
+<p>See the <a href="../coding/#type-checking">type checking</a> and <a href="../coding/#linting">linting</a> examples.</p>
 
 
 

diff --git a/docs/search/search_index.json b/docs/search/search_index.json
diff --git a/docs/sitemap.xml b/docs/sitemap.xml
@@ -2,102 +2,102 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://dsa-ou.github.io/algoesup/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/coding/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/deepnote-background/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/deepnote-how-to/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/deepnote-reference/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/deepnote/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/example-essays/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/feedback/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/getting-started-google-colab/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/getting-started-m269/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/getting-started/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/jn-platform-comparison/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/library/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/writing/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/essays/example-1-to-n/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/essays/example-jewels/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/essays/example-two-sum-2/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/essays/example-two-sum-3/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/essays/template-data-structures/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/essays/template-intro-programming/</loc>
-         <lastmod>2024-08-14</lastmod>
+         <lastmod>2024-08-28</lastmod>
          <changefreq>daily</changefreq>
     </url>
 </urlset>
diff --git a/docs/sitemap.xml.gz b/docs/sitemap.xml.gz
diff --git a/src/algoesup/magics.py b/src/algoesup/magics.py
@@ -1,4 +1,7 @@
-"""Linting tools for Jupyter Notebook environments"""
+"""Linting tools for Jupyter Notebook environments.
+
+See the [type checking](coding.ipynb#type-checking) and [linting](coding.ipynb#linting) examples.
+"""
 
 import argparse
 import json

diff --git a/src/algoesup/test.py b/src/algoesup/test.py
@@ -1,4 +1,4 @@
-"""Simplified testing for Python functions"""
+"""Simplified testing for Python functions, see the [examples](coding.ipynb#testing)."""
 
 from typing import Callable
 

diff --git a/src/algoesup/time.py b/src/algoesup/time.py
@@ -1,4 +1,4 @@
-"""Tools for measuring and plotting run-times"""
+"""Tools for measuring and plotting run-times, see the [examples](coding.ipynb#performance-analysis)."""
 
 from typing import Callable
 
@@ -57,9 +57,9 @@ def time_cases(
     chart: bool = False,
 ) -> None:
     """Print or plot the run-times of `function` for different input cases.
-    
-    `time_cases` prints or plots the run-times of a single function using a list of 
-    different input generators. Inputs are generated based on a starting size and are 
+
+    `time_cases` prints or plots the run-times of a single function using a list of
+    different input generators. Inputs are generated based on a starting size and are
     doubled a specified number of times.
 
     Args:
@@ -70,7 +70,7 @@ def time_cases(
         double (int): The number of times to double the input size. Must be non-negative.
         text (bool, optional): If True, print the run-times in text format.
         chart (bool, optional): If True, plot the run-times using a chart.
-    
+
     Raises:
         AssertionError: If input conditions are not satisfied.
     """
@@ -129,8 +129,8 @@ def time_functions(
 ) -> None:
     """Print or plot the run-times of different functions for the same inputs.
 
-    `time_functions` prints or plots the run-times given list of functions and an input 
-    generator. Inputs are generated based on a starting size and are doubled a specified 
+    `time_functions` prints or plots the run-times given list of functions and an input
+    generator. Inputs are generated based on a starting size and are doubled a specified
     number of times.
 
     Args:
@@ -203,7 +203,7 @@ def time_functions_int(
     chart: bool = True,
 ) -> None:
     """Time functions that take a single integer as input.
-    
+
     `time_functions_int` uses `time_functions` to measure and display the run-times
     of a given list of functions that accept a single integer input. The integer inputs
     are generated starting from a specified value that defaults to 1, and are doubled
@@ -218,7 +218,7 @@ def time_functions_int(
             Must be positive.
         double (int, optional): The number of times to double the input integer value.
             Defaults to 10. Must be non-negative.
-        text (bool, optional): If True, print the run-times in text format. 
-        chart (bool, optional): If True, plot the run-times using a chart. 
+        text (bool, optional): If True, print the run-times in text format.
+        chart (bool, optional): If True, plot the run-times using a chart.
     """
     time_functions(functions, generator, start, double, text, chart, True)
diff --git a/src/docs/library.md b/src/docs/library.md
@@ -1,6 +1,7 @@
 # Library
 
 The `algoesup` library provides support for testing, timing and linting code.
+This documentation is for version 0.3.1.
 
 ## Testing