README.md

McCole

A template for Ark-based tutorials.

1. Set up Python environment:

   1. Create lib/mccole/.
   2. Create lib/mccole/requirements.txt.
   3. Add ark and pymdown-extensions to lib/mccole/requirements.txt.
   4. Create requirements.txt with -r lib/mccole/requirements.txt.
   5. Create conda environment mccole.
   6. Install packages with pip install -r requirements.txt.

2. Set up minimal Ark site:

   1. Create config.py.
   2. Define title, repo, and author.
   3. Define theme to be mccole.
   4. Define src_dir to be src.
   5. Define out_dir to be docs.
   6. Define extension to be /.
   7. Enable Markdown extensions.
   8. Create empty src/index.md.
   9. Create lib/mccole/templates/node.ibis template with nothing but {{node.html}}.

3. Create license and code of conduct pages:

   1. Create LICENSE.md and CODE_OF_CONDUCT.md for GitHub to display.
   2. Create src/license/index.md and src/conduct/index.md to generate pages in docs.
   3. Define rootfile shortcode in lib/mccole/extensions/rootfile.py to include files from the root.
   4. Create lib/mccole/extensions/util.py to hold utilities.
   5. Add __pycache__ to .gitignore to stop util.pyc from being included in Git.

4. Create glossary.

   1. Add src/glossary/index.md with [% glossary %] shortcode.
   2. Add [%g ssg "text" %] to src/index.md as test case.
   3. Create info/glossary.yml with Glosario-format glossary.
   4. Add lang="en" to config.py to specify language.
   5. Create lib/mccole/extensions/glossary.py with implementation of glossary and g shortcodes.
   6. Add test case for g shortcode to src/index.md.
   7. Add markdownify function to lib/mccole/extensions/util.py for Markdown conversion.

5. Automation.

   1. Create Makefile that includes lib/mccole/mccole.mk.
   2. Create lib/mccole/mccole.mk with targets to rebuild and check.
   3. Add ruff to lib/mccole/requirements.txt and install it.

6. Style pages.

   1. Create lib/mccole/resources/mccole.css with beginnings of (unresponsive) styling.
   2. Add HTML layout to lib/mccole/templates/node.ibis.
   3. Add head.html and foot.html to lib/mccole/templates directory.
   4. Add lib/mccole/resources/logo.svg for use as favicon.
   5. Add .nojekyll file to prevent GitHub from re-rendering pages.

7. Add front matter to index.md pages with titles.

8. Add cross-referencing and table of contents.

   1. Add chapters and appendices to config.py to define order.
   2. Add _number_contents and _collect_titles to lib/mccole/extensions/init.py to gather information.
   3. Create lib/mccole/extensions/toc.py for cross-references and table of contents.
   4. Add x shortcode to cross-reference chapters and appendices.
   5. Add toc shortcode to create table of contents.
   6. Add src/intro/index.md and src/finale/index.md as test cases.

9. Add bibliography.

   1. Modify lib/mccole/requirements.txt to install pybtex package.
   2. Add info/bibliography.bib (BibTeX-formatted bibliography).
   3. Add lib/mccole/bin/make_bibliography.py to translate BibTeX into HTML in tmp/bibliography.html.
   4. Modify lib/mccole/mccole.mk to build HTML version of bibliography.
   5. Modify lib/mccole/resources/mccole.mk to display bibliography.
   6. Add bibliography shortcode to include bibliography in page.
   7. Add b shortcode to reference bibliography entries.
   8. Add src/bib/index.md to show bibliography.
   9. Modify config.py to include bib as appendix.

10. Add figures and tables.

    1. Add lib/mccole/extensions/figure.py with shortcode f and figure inclusion figure.
    2. Add lib/mccole/extensions/table.py with shortcode t and figure inclusion table.
    3. Rename lib/mccole/extensions/init.py to lib/mccole/extensions/batch.py to reflect purpose.
    4. Add startup task in lib/mccole/extensions/batch.py to find and number all figures and tables.
    5. Add copy field to config.py with globs of files to copy directly (just *.svg for now).
    6. Add finalization code to lib/mccole/extensions/batch.py to copy files.
    7. Add examples of figures and tables (and references) to src/intro/index.md and src/finale/index.md.
    8. Move localization into lib/mccole/extensions/util.py.

11. Add navigation links and a proper title.

    1. Collect all metadata in lib/mccole/extensions/batch.py.
    2. Add lib/mccole/templates/title.html to format title and prev/next navigation links.
    3. Include title.html in lib/mccole/templates/node.ibis.
    4. Add lib/mccole/extensions/filters.py with various filters required by template additions.
    5. Add flex grid to lib/mccole/resources/mccole.css.
    6. Modify src/license/index.md and src/conduct/index.md to strip inherited title of root pages.

12. Add links to pages.

    1. Add info/links.yml with link definitions.
    2. Add ensure_links function to lib/mccole/extensions/util.py to load and format links.
    3. Add _append_links function to lib/mccole/extensions/batch.py to append link text to files.
    4. Add src/colophon/index.md to display credits.

13. Add list of defined terms to pages.

    1. Move glossary loading to lib/mccole/extensions/util.py and cache.
    2. Refactor shortcode collection in lib/mccole/extensions/batch.py.
    3. Add collection of glossary keys in lib/mccole/extensions/batch.py.
    4. Add filter termdefs in lib/mccole/extensions/filters.py to display defined terms.
    5. Move glossary reference test into src/intro/index.md.
    6. Modify lib/mccole/templates/node.ibis to show defined terms.

14. Refactor.

    1. Move larger filters like termdefs into files of their own.
    2. Add hooks to exclude directories and files.
    3. Add copy and exclude keys to config.py.
    4. Add fixme shortcode for notes.
    5. Add target to lib/mccole/mccole.mk to build zip file and to check things after unpacking it.

15. Add features after trying it out.

    1. Add contributors' guide in CONTRIBUTING.md and page in src/contrib/index.md.
    2. Add MathJax to lib/mccole/templates/head.html.
    3. Add link to home page to lib/mccole/templates/foot.html.
    4. Add colored sidebars to lib/mccole/resources/mccole.css.
    5. Add stamp colors and Danielle Navarro to colophon.

16. Add thanks.

    1. Add lib/mccole/extensions/thanks.py to read and format info/thanks.yml.
    2. Add usage to src/intro/index.md to test.

17. Add index.

    1. Add lib/mccole/extensions/index.py to format index and index references.
    2. Modify lib/mccole/extensions/batch.py to collect index references.
    3. Add src/contents/index.md to display index (using contents instead of index to avoid confusion).
    4. Modify lib/mccole/mccole.mk to include src/contents/index.md in zip file.

18. Add linting.

    1. Add lib/mccole/bin/lint.py and lib/mccole/bin/lint_svg.py to check project features.
    2. Add targets to lib/mccole/mccole.mk to run them.

19. CSS improvements.

    1. Responsive layout.
    2. Reduce indentation of bullet lists.
    3. Label navigation controls with <nav> element.
    4. Unify colors and borders of code inclusions.
    5. Syntax highlighting.

20. Add profiling.

    1. Add lib/mccole/bin/run_profile.py to profile build.
    2. Add target to lib/mccole/mccole.mk to run it.

21. Improve contribution guide.