Skip to content

Commit

Permalink
feat: better contribution guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@gvwilson
gvwilson committed Apr 8, 2024
1 parent f58388d commit 20dcfb5
Show file tree
Hide file tree
Showing 2 changed files with 249 additions and 31 deletions.
122 changes: 107 additions & 15 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,52 +4,144 @@ 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.

- 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,
and unfilled objects.

## 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/
158 changes: 142 additions & 16 deletions docs/contrib/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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&rsquo;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&rsquo;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&rsquo;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.
Expand All @@ -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>
Expand All @@ -100,13 +179,60 @@ <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,
and unfilled objects.</p>
</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&rsquo;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&rsquo;s uncomfortable enough to use that people won&rsquo;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&rsquo;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&rsquo; lives better,
build a diff-and-merge tool for SVG:
programmers shouldn&rsquo;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&rsquo;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>
Expand Down

0 comments on commit 20dcfb5

Please sign in to comment.