Fix #29: options for linters (#30)

* Pass arbitrary options to the linters (but `on` must be first argument) * If linter exits with status > 0, display error, unless it's syntax error * Add `black` for formatting headers in library docs * Update and regenerate docs * Update .gitignore --------- Co-authored-by: michael <[email protected]>
dsa-ou · Apr 4, 2024 · 30abe15 · 30abe15
1 parent 0deff03
commit 30abe15
Show file tree

Hide file tree

Showing 12 changed files with 281 additions and 195 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,7 @@
 # https://github.com/github/gitignore/blob/main/Python.gitignore
 
+.vscode/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

diff --git a/docs/essays/example-1-to-n/index.html b/docs/essays/example-1-to-n/index.html
@@ -1348,7 +1348,7 @@ <h1 id="sum-of-1-to-n">Sum of 1 to <em>n</em><a class="anchor-link" href="#sum-o
 <div class="jp-Collapser jp-InputCollapser jp-Cell-inputCollapser">
 </div>
 <div class="jp-InputArea jp-Cell-inputArea">
-<div class="jp-InputPrompt jp-InputArea-prompt">In [2]:</div><div class="jp-CodeMirrorEditor jp-Editor jp-InputArea-editor" data-type="inline">
+<div class="jp-InputPrompt jp-InputArea-prompt">In [4]:</div><div class="jp-CodeMirrorEditor jp-Editor jp-InputArea-editor" data-type="inline">
 <div class="CodeMirror cm-s-jupyter">
 <div class="zeroclipboard-container">
 <clipboard-copy for="cell-3">
@@ -1365,13 +1365,13 @@ <h1 id="sum-of-1-to-n">Sum of 1 to <em>n</em><a class="anchor-link" href="#sum-o
 <span class="c1"># check the code for style violations</span>
 <span class="o">%</span><span class="n">ruff</span> <span class="n">on</span>
 <span class="c1"># check that only the subset of Python taught in our introductory course TM112 is used</span>
-<span class="o">%</span><span class="n">allowed</span> <span class="o">--</span><span class="n">config</span> <span class="n">tm112</span><span class="o">.</span><span class="n">json</span> <span class="n">on</span>
+<span class="o">%</span><span class="n">allowed</span> <span class="n">on</span> <span class="o">--</span><span class="n">config</span> <span class="n">tm112</span><span class="o">.</span><span class="n">json</span>
 </pre></div>
 <div class="clipboard-copy-txt" id="cell-3">%load_ext algoesup.magics
 # check the code for style violations
 %ruff on
 # check that only the subset of Python taught in our introductory course TM112 is used
-%allowed --config tm112.json on</div>
+%allowed on --config tm112.json</div>
 </div>
 </div>
 </div>

diff --git a/docs/library/index.html b/docs/library/index.html
@@ -1140,7 +1140,15 @@ <h3 id="algoesup.time.time_functions" class="doc doc-heading">
 
 
 </h3>
-<div class="doc-signature highlight"><pre><span></span><code><span class="n">time_functions</span><span class="p">(</span><span class="n">functions</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">Callable</span><span class="p">],</span> <span class="n">inputs</span><span class="p">:</span> <span class="n">Callable</span><span class="p">,</span> <span class="n">start</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">double</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">text</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span> <span class="n">chart</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span> <span class="n">value</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
+<div class="doc-signature highlight"><pre><span></span><code><span class="n">time_functions</span><span class="p">(</span>
+    <span class="n">functions</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">Callable</span><span class="p">],</span>
+    <span class="n">inputs</span><span class="p">:</span> <span class="n">Callable</span><span class="p">,</span>
+    <span class="n">start</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
+    <span class="n">double</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
+    <span class="n">text</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span>
+    <span class="n">chart</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
+    <span class="n">value</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
+<span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
 </code></pre></div>
 
   <div class="doc doc-contents ">
@@ -1303,7 +1311,14 @@ <h3 id="algoesup.time.time_cases" class="doc doc-heading">
 
 
 </h3>
-<div class="doc-signature highlight"><pre><span></span><code><span class="n">time_cases</span><span class="p">(</span><span class="n">function</span><span class="p">:</span> <span class="n">Callable</span><span class="p">,</span> <span class="n">cases</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">Callable</span><span class="p">],</span> <span class="n">start</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">double</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">text</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span> <span class="n">chart</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
+<div class="doc-signature highlight"><pre><span></span><code><span class="n">time_cases</span><span class="p">(</span>
+    <span class="n">function</span><span class="p">:</span> <span class="n">Callable</span><span class="p">,</span>
+    <span class="n">cases</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">Callable</span><span class="p">],</span>
+    <span class="n">start</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
+    <span class="n">double</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
+    <span class="n">text</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span>
+    <span class="n">chart</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
+<span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
 </code></pre></div>
 
   <div class="doc doc-contents ">
@@ -1452,7 +1467,14 @@ <h3 id="algoesup.time.time_functions_int" class="doc doc-heading">
 
 
 </h3>
-<div class="doc-signature highlight"><pre><span></span><code><span class="n">time_functions_int</span><span class="p">(</span><span class="n">functions</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">Callable</span><span class="p">],</span> <span class="n">generator</span><span class="p">:</span> <span class="n">Callable</span> <span class="o">=</span> <span class="n">int_value</span><span class="p">,</span> <span class="n">start</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="n">double</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">,</span> <span class="n">text</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span> <span class="n">chart</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
+<div class="doc-signature highlight"><pre><span></span><code><span class="n">time_functions_int</span><span class="p">(</span>
+    <span class="n">functions</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">Callable</span><span class="p">],</span>
+    <span class="n">generator</span><span class="p">:</span> <span class="n">Callable</span> <span class="o">=</span> <span class="n">int_value</span><span class="p">,</span>
+    <span class="n">start</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
+    <span class="n">double</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">,</span>
+    <span class="n">text</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span>
+    <span class="n">chart</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span>
+<span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
 </code></pre></div>
 
   <div class="doc doc-contents ">
@@ -1620,14 +1642,16 @@ <h3 id="algoesup.magics.allowed" class="doc doc-heading">
 <p>When active, the linter checks each code cell that is executed for any
 Python constructs that are not listed in the given configuration file.</p>
 <ul>
-<li><code>%allowed --config ... on</code> activates the linter with the given configuration,
-  which must be <code>m269.json</code>, <code>tm112.json</code> or 
-  <a href="https://dsa-ou.github.io/allowed/docs/configuration.html">one you defined</a></li>
-<li><code>%allowed on</code> is equal to <code>%allowed --config m269.json on</code></li>
+<li><code>%allowed on ...</code> activates the linter with any command options given after <code>on</code></li>
+<li><code>%allowed on</code> is equal to <code>%allowed on --config m269.json</code></li>
 <li><code>%allowed off</code> deactivates the linter</li>
 <li><code>%allowed</code> shows the current status of the linter</li>
 <li><code>%allowed?</code> shows this documentation and the command&rsquo;s options</li>
 </ul>
+<p>For a list of possible options <code>...</code>, enter <code>!allowed -h</code> in a code cell.
+Some options may not be appropriate when running <code>allowed</code> within a notebook.</p>
+<p>The <code>--config</code> option expects <code>m269.json</code>, <code>tm112.json</code> or the name of a JSON file
+with your own <a href="https://dsa-ou.github.io/allowed/docs/configuration.html">configuration</a>.</p>
 
   </div>
 
@@ -1651,13 +1675,16 @@ <h3 id="algoesup.magics.pytype" class="doc doc-heading">
       <p>Activate/deactivate the <a href="https://google.github.io/pytype">pytype linter</a>.</p>
 <p>When active, the linter checks each code cell that is executed for type errors.</p>
 <ul>
-<li><code>%pytype --disable ... on</code> activates the linter but does not check the given errors
-  (see the <a href="https://google.github.io/pytype/errors.html">list of errors</a>)</li>
-<li><code>%pytype on</code> is equal to <code>%pytype --disable name-error,import-error on</code></li>
+<li><code>%pytype on ...</code> activates the linter with the command options given after <code>on</code></li>
+<li><code>%pytype on</code> is equal to <code>%pytype on --disable name-error,import-error</code></li>
 <li><code>%pytype off</code> deactivates the linter</li>
 <li><code>%pytype</code> shows the current status of the linter</li>
 <li><code>%pytype?</code> shows this documentation and the command&rsquo;s options</li>
 </ul>
+<p>For a list of possible options <code>...</code>, enter <code>!pytype -h</code> in a code cell.
+Some options may not be appropriate when running pytype within a notebook.</p>
+<p>The <code>--disable</code> option expects a list of 
+<a href="https://google.github.io/pytype/errors.html">errors</a> to ignore, without spaces.</p>
 
   </div>
 
@@ -1682,13 +1709,18 @@ <h3 id="algoesup.magics.ruff" class="doc doc-heading">
 <p>When active, the linter checks each code cell that is executed
 against the selected code style rules.</p>
 <ul>
-<li><code>%ruff --select ... --ignore ... on</code> activates the linter with the given rules
-  (see <a href="https://docs.astral.sh/ruff/rules">the list of rules</a>)</li>
-<li><code>%ruff on</code> is equal to <code>%ruff --select A,B,C90,D,E,W,F,N,PL --ignore D100,W292,F401,F821,D203,D213,D415 on</code></li>
+<li><code>%ruff on ...</code> activates the linter with any command options given after <code>on</code>
+  (see [ruff&rsquo;s list of rules])</li>
+<li><code>%ruff on</code> is equal to <code>%ruff on --select A,B,C90,D,E,W,F,N,PL --ignore D100,W292,F401,F821,D203,D213,D415</code></li>
 <li><code>%ruff off</code> deactivates the linter</li>
 <li><code>%ruff</code> shows the current status of the linter</li>
-<li><code>%ruff?</code> shows this documentation and the command&rsquo;s options</li>
+<li><code>%ruff?</code> shows this documentation</li>
 </ul>
+<p>The command <code>%ruff on ...</code> will run <code>ruff check --output-format json ...</code> on each cell. 
+For a list of the possible options <code>...</code>, enter <code>!ruff help check</code> in a code cell.
+Some options may not be appropriate when running Ruff within a notebook.</p>
+<p>The <code>--select</code> and <code>--ignore</code> options expect a list
+of <a href="https://docs.astral.sh/ruff/rules">rule codes</a>, without spaces.</p>
 
   </div>
 

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,92 +2,92 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://dsa-ou.github.io/algoesup/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/deepnote-background/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/deepnote-how-to/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/deepnote-reference/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/deepnote/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/example-essays/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/feedback/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/getting-started-google-colab/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/getting-started-m269/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/getting-started/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/library/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/writing/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/essays/example-1-to-n/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/essays/example-jewels/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/essays/example-two-sum-2/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/essays/example-two-sum-3/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/essays/template-data-structures/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://dsa-ou.github.io/algoesup/essays/template-intro-programming/</loc>
-         <lastmod>2024-03-19</lastmod>
+         <lastmod>2024-04-02</lastmod>
          <changefreq>daily</changefreq>
     </url>
 </urlset>
diff --git a/docs/sitemap.xml.gz b/docs/sitemap.xml.gz
diff --git a/docs/writing/index.html b/docs/writing/index.html
@@ -1191,7 +1191,7 @@ <h2 id="problem">Problem</h2>
 <p>It&rsquo;s worth spending time on choosing an appropriate problem before putting effort into an essay about it.
 You may invent your own problem or select an existing one.
 For example, it may be a non-assessed exercise from your course, or
-it may relate to your hobby or work. In so, provide any information the reader needs to understand the problem.
+it may relate to your hobby or work. If so, provide any information the reader needs to understand the problem.
 If the problem is from your work, get permission from your employer or client.</p>
 <p>There are <a href="https://www.freecodecamp.org/news/the-most-popular-coding-challenge-websites/">many websites</a> with thousands of algorithmic problems to choose from.
 We have used <a href="https://open.kattis.com">Kattis</a> and <a href="https://leetcode.com/problemset/all/">LeetCode</a> in the past.</p>
@@ -1404,7 +1404,7 @@ <h3 id="type-checking">Type checking</h3>
 You may thus wish to initially turn off the type checking, with <code>%pytype off</code>,
 and only turn it on after all code is written and tested.
 You will have to run all cells of your notebook for the type checking to take place.</p>
-<p>For a list of all the options for the <code>%pytype</code> command, 
+<p>For a list of all the options for the <code>%pytype</code> command,
 see the <a href="../library/#algoesup.magics.pytype">library reference</a>.</p>
 <h3 id="formatting">Formatting</h3>
 <div class="admonition note">
@@ -1425,7 +1425,7 @@ <h3 id="formatting">Formatting</h3>
 <h3 id="linting">Linting</h3>
 <p>You should <strong>lint</strong> your code, which means to check it for style violations.</p>
 <h4 id="code-style">Code style</h4>
-<p>Our library support <code>ruff</code>, the fastest Python linter. 
+<p>Our library supports <code>ruff</code>, the fastest Python linter.
 To turn it on, write the following after loading the <code>algoesup.magics</code> extension.
 <div class="highlight"><pre><span></span><code><span class="o">%</span><span class="n">ruff</span> <span class="n">on</span>
 </code></pre></div></p>
@@ -1509,7 +1509,7 @@ <h4 id="language-subset">Language subset</h4>
 if it has several constructs that weren&rsquo;t taught, none of them is reported.</p>
 <p>The <code>allowed</code> linter also includes the configuration for TM112, our introductory Computing course,
 in case you want to use even fewer constructs in your essay.
-To use that configuration, write <code>%allowed --config tm112.json on</code>.
+To use that configuration, write <code>%allowed on --config tm112.json</code>.
 For a list of all the options for the <code>%allowed</code> command, 
 see the <a href="../library/#algoesup.magics.allowed">library reference</a>.</p>
 <p>You can configure the linter with a JSON file that lists the allowed constructs.