diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 69b089c..e2c2509 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,37 +4,71 @@ Contributions are very welcome. Please file issues or submit pull requests in [our GitHub repository][repo]. All contributors will be acknowledged. -## In Brief +## Setup - Use `pip install -r requirements.txt` to install the packages required by the helper tools and Python examples. You may wish to create a new virtual environment before doing so. All code has been tested with Python 3.12.1. -- Content lives in the `.md` files under the `src` directory - and is translated into a static website using [Ark][ark]. - Each page must be in its own sub-directory except for `src/index.md`, - which becomes the site's home page. +- Run `make` without arguments to see available commands + Of these, + `make build` to rebuild everything in `./docs` + and `make serve` to run a local preview server + are the most immediately useful. -- `Makefile` references `lib/mccole/mccole.mk`; - typing `make` by itself on the command line will list available targets. +| Command | Action | +| ------------ | ------ | +| `commands` | show available commands | +| `build` | rebuild site without running server | +| `serve` | build site and run server | +| `profile` | profile compilation | +| `bib` | rebuild HTML version of bibliography | +| `lint` | check project | +| `style` | check Python code style | +| `reformat` | reformat unstylish Python code | +| `pack` | create a release | +| `unpack` | make required files after unzipping mccole.zip | +| `clean` | clean up stray files | -- All external links are written using `[box][notation]` inline - and defined in `info/tutorial.yml`. +## Layout + +- This template uses [Ark][ark] to compile Markdown with embedded shortcode directives + into a static HTML site under `docs/`. + +- The McCole theme lives in `lib/mccole`: + - `bin/`: utility scripts + - `colophon.yml`: links used in the colophon + - `extensions/`: shortcodes and other extensions to Ark used by the theme + - `mccole.mk`: targets and commands common to all projects that use this theme + - `requirements.txt`: packages common to all projects that use this theme + - `resources/`: CSS files and other resources used by this theme + - `templates/`: HTML templates used by this theme (the main one being `node.ibis`). + +- The site's configuration lives in `config.py`. + The lists `chapters` and `appendices` define slugs for the sections, in order. + +- Content lives in `.md` files in subdirectories under `src` + Each section must be in its own subdirectory except for `src/index.md`, + which is the site's home page. + +- Please write external links using `[box][notation]` + and define links in `info/tutorial.yml` + rather than putting links inline. + Doing this will help ensure consistency across pages. - Use `[%x slug %]` to create a cross-reference to a chapter or appendix, - where the slug is the name of a sub-directory under `src`. + where the slug is the name of a subdirectory under `src`. - Use `[%g key "text" %]` to link to glossary entries. The text is inserted and highlighted; the key must identify an entry in `info/glossary.yml`, which is in [Glosario][glosario] format. -- Use `[%b key1 key2 %]` to cite bibliography entries, - which are stored in BibTeX format in `info/bibliography.bib`. - -- Use `[%inc filename %]` to include a text file containing code or sample output - in a Markdown file. +- Use `[%b key1 key2 %]` to cite bibliography entries. + The keys must appear in `info/bibliography.bib`, + which is stored in BibTeX format + and compiled to create `tmp/bibliography.html`. - Use `[%figure slug="some_slug" img="some_file.ext" caption="the caption" alt="alt text" %]` to create a figure and `[%f some_slug %]` to refer to it. @@ -42,6 +76,11 @@ All contributors will be acknowledged. - Use `[%table slug="some_slug" tbl="some_file.tbl" caption="the caption" %]` to create a table and `[%g some_slug %]` to refer to it. +- Use `[%inc filename %]` to include a text file containing code or sample output + in a Markdown file. + If the inclusion contains `mark=label` + then only code between comments marked `[label]` and `[/label]` will be included. + - SVG diagrams can be edited using [draw.io][draw_io]. Please use 14-point Helvetica for text, solid 1-point black lines, @@ -49,7 +88,60 @@ All contributors will be acknowledged. ## FAQ +What is this for? +: I wrote [a short SQL tutorial][sql] in 2024, + and am currently working on one about [systems programming][sys] + and another about [research software design][rsdx]. + I was initially going to use the template I built for + the [JavaScript][sdxjs] and [Python][sdxpy] versions of *Software Design by Example*, + but realized I could slim it down, + speed it up, + and make it prettier. + Some people knit + some play video games, + I like to type… + +Why Ark? +: [Jekyll][jekyll] is the default for [GitHub Pages][ghp], + but very few data scientists use Ruby + so previewing changes locally would require them to install and use + yet another language framework. + In addition, + GitHub Pages doesn't allow arbitrary extensions for security reasons, + so the only way to implement things like bibliography citations and glossary references + is to use its (rather verbose) inclusions and (rather clumsy) scripting features. + +Why Make? +: It runs everywhere, + no other build tool is a clear successor, + and, + like Jekyll, + it's uncomfortable enough to use that people won't be tempted to fiddle with it + when they could be writing content. + +Why hand-drawn figures rather than [Graphviz][graphviz] or [Mermaid][mermaid]? +: Because it's faster to Just Effing Draw than it is + to try to tweak layout parameters for text-to-diagram systems. + If you really want to make developers' lives better, + build a diff-and-merge tool for SVG: + programmers shouldn't have to use punchard-compatible data formats in the 21st Century + just to get the benefits of version control. + +Why McCole? +: Because it was my father's middle name. + He was my high school English teacher for five years (it was a small town), + and I learned most of what I know about writing from him. + [ark]: https://www.dmulholl.com/docs/ark/main/ [draw_io]: https://www.drawio.com/ +[ghp]: https://pages.github.com/ [glosario]: https://glosario.carpentries.org/ +[graphviz]: https://graphviz.org/ +[jekyll]: https://jekyllrb.com/ +[mermaid]: https://mermaid.js.org/ [repo]: https://github.com/gvwilson/mccole/ +[rsdx]: https://gvwilson.github.io/rsdx/ +[sdxjs]: https://third-bit.com/sdxjs/ +[sdxpy]: https://third-bit.com/sdxpy/ +[sql]: https://gvwilson.github.io/sql-tutorial/ +[sys]: https://gvwilson.github.io/sql-tutorial/ diff --git a/docs/contrib/index.html b/docs/contrib/index.html index 3ffa117..b612c4a 100644 --- a/docs/contrib/index.html +++ b/docs/contrib/index.html @@ -51,7 +51,7 @@ <h1>Contributing</h1> <p>Contributions are very welcome. Please file issues or submit pull requests in <a href="https://github.com/gvwilson/mccole/">our GitHub repository</a>. All contributors will be acknowledged.</p> -<h2>In Brief</h2> +<h2>Setup</h2> <ul> <li> <p>Use <code>pip install -r requirements.txt</code> @@ -60,22 +60,103 @@ <h2>In Brief</h2> All code has been tested with Python 3.12.1.</p> </li> <li> -<p>Content lives in the <code>.md</code> files under the <code>src</code> directory - and is translated into a static website using <a href="https://www.dmulholl.com/docs/ark/main/">Ark</a>. - Each page must be in its own sub-directory except for <code>src/index.md</code>, - which becomes the site’s home page.</p> +<p>Run <code>make</code> without arguments to see available commands + Of these, + <code>make build</code> to rebuild everything in <code>./docs</code> + and <code>make serve</code> to run a local preview server + are the most immediately useful.</p> +</li> +</ul> +<table> +<thead> +<tr> +<th>Command</th> +<th>Action</th> +</tr> +</thead> +<tbody> +<tr> +<td><code>commands</code></td> +<td>show available commands</td> +</tr> +<tr> +<td><code>build</code></td> +<td>rebuild site without running server</td> +</tr> +<tr> +<td><code>serve</code></td> +<td>build site and run server</td> +</tr> +<tr> +<td><code>profile</code></td> +<td>profile compilation</td> +</tr> +<tr> +<td><code>bib</code></td> +<td>rebuild HTML version of bibliography</td> +</tr> +<tr> +<td><code>lint</code></td> +<td>check project</td> +</tr> +<tr> +<td><code>style</code></td> +<td>check Python code style</td> +</tr> +<tr> +<td><code>reformat</code></td> +<td>reformat unstylish Python code</td> +</tr> +<tr> +<td><code>pack</code></td> +<td>create a release</td> +</tr> +<tr> +<td><code>unpack</code></td> +<td>make required files after unzipping mccole.zip</td> +</tr> +<tr> +<td><code>clean</code></td> +<td>clean up stray files</td> +</tr> +</tbody> +</table> +<h2>Layout</h2> +<ul> +<li> +<p>This template uses <a href="https://www.dmulholl.com/docs/ark/main/">Ark</a> to compile Markdown with embedded shortcode directives + into a static HTML site under <code>docs/</code>.</p> +</li> +<li> +<p>The McCole theme lives in <code>lib/mccole</code>:</p> +<ul> +<li><code>bin/</code>: utility scripts</li> +<li><code>colophon.yml</code>: links used in the colophon</li> +<li><code>extensions/</code>: shortcodes and other extensions to Ark used by the theme</li> +<li><code>mccole.mk</code>: targets and commands common to all projects that use this theme</li> +<li><code>requirements.txt</code>: packages common to all projects that use this theme</li> +<li><code>resources/</code>: CSS files and other resources used by this theme</li> +<li><code>templates/</code>: HTML templates used by this theme (the main one being <code>node.ibis</code>).</li> +</ul> </li> <li> -<p><code>Makefile</code> references <code>lib/mccole/mccole.mk</code>; - typing <code>make</code> by itself on the command line will list available targets.</p> +<p>The site’s configuration lives in <code>config.py</code>. + The lists <code>chapters</code> and <code>appendices</code> define slugs for the sections, in order.</p> </li> <li> -<p>All external links are written using <code>[box][notation]</code> inline - and defined in <code>info/tutorial.yml</code>.</p> +<p>Content lives in <code>.md</code> files in subdirectories under <code>src</code> + Each section must be in its own subdirectory except for <code>src/index.md</code>, + which is the site’s home page.</p> +</li> +<li> +<p>Please write external links using <code>[box][notation]</code> + and define links in <code>info/tutorial.yml</code> + rather than putting links inline. + Doing this will help ensure consistency across pages.</p> </li> <li> <p>Use <code>[%x slug %]</code> to create a cross-reference to a chapter or appendix, - where the slug is the name of a sub-directory under <code>src</code>.</p> + where the slug is the name of a subdirectory under <code>src</code>.</p> </li> <li> <p>Use <code>[%g key "text" %]</code> to link to glossary entries. @@ -84,12 +165,10 @@ <h2>In Brief</h2> which is in <a href="https://glosario.carpentries.org/">Glosario</a> format.</p> </li> <li> -<p>Use <code>[%b key1 key2 %]</code> to cite bibliography entries, - which are stored in BibTeX format in <code>info/bibliography.bib</code>.</p> -</li> -<li> -<p>Use <code>[%inc filename %]</code> to include a text file containing code or sample output - in a Markdown file.</p> +<p>Use <code>[%b key1 key2 %]</code> to cite bibliography entries. + The keys must appear in <code>info/bibliography.bib</code>, + which is stored in BibTeX format + and compiled to create <code>tmp/bibliography.html</code>.</p> </li> <li> <p>Use <code>[%figure slug="some_slug" img="some_file.ext" caption="the caption" alt="alt text" %]</code> @@ -100,6 +179,12 @@ <h2>In Brief</h2> to create a table and <code>[%g some_slug %]</code> to refer to it.</p> </li> <li> +<p>Use <code>[%inc filename %]</code> to include a text file containing code or sample output + in a Markdown file. + If the inclusion contains <code>mark=label</code> + then only code between comments marked <code>[label]</code> and <code>[/label]</code> will be included.</p> +</li> +<li> <p>SVG diagrams can be edited using <a href="https://www.drawio.com/">draw.io</a>. Please use 14-point Helvetica for text, solid 1-point black lines, @@ -107,6 +192,47 @@ <h2>In Brief</h2> </li> </ul> <h2>FAQ</h2> +<dl> +<dt>What is this for?</dt> +<dd>I wrote <a href="https://gvwilson.github.io/sql-tutorial/">a short SQL tutorial</a> in 2024, +and am currently working on one about <a href="https://gvwilson.github.io/sql-tutorial/">systems programming</a> +and another about <a href="https://gvwilson.github.io/rsdx/">research software design</a>. +I was initially going to use the template I built for +the <a href="https://third-bit.com/sdxjs/">JavaScript</a> and <a href="https://third-bit.com/sdxpy/">Python</a> versions of <em>Software Design by Example</em>, +but realized I could slim it down, +speed it up, +and make it prettier. +Some people knit +some play video games, +I like to type…</dd> +<dt>Why Ark?</dt> +<dd><a href="https://jekyllrb.com/">Jekyll</a> is the default for <a href="https://pages.github.com/">GitHub Pages</a>, +but very few data scientists use Ruby +so previewing changes locally would require them to install and use +yet another language framework. +In addition, +GitHub Pages doesn’t allow arbitrary extensions for security reasons, +so the only way to implement things like bibliography citations and glossary references +is to use its (rather verbose) inclusions and (rather clumsy) scripting features.</dd> +<dt>Why Make?</dt> +<dd>It runs everywhere, +no other build tool is a clear successor, +and, +like Jekyll, +it’s uncomfortable enough to use that people won’t be tempted to fiddle with it +when they could be writing content.</dd> +<dt>Why hand-drawn figures rather than <a href="https://graphviz.org/">Graphviz</a> or <a href="https://mermaid.js.org/">Mermaid</a>?</dt> +<dd>Because it’s faster to Just Effing Draw than it is +to try to tweak layout parameters for text-to-diagram systems. +If you really want to make developers’ lives better, +build a diff-and-merge tool for SVG: +programmers shouldn’t have to use punchard-compatible data formats in the 21st Century +just to get the benefits of version control.</dd> +<dt>Why McCole?</dt> +<dd>Because it was my father’s middle name. +He was my high school English teacher for five years (it was a small town), +and I learned most of what I know about writing from him.</dd> +</dl> </main> <footer> © 2024 <a href="https://third-bit.com/">Greg Wilson</a>