Metadata-Version: 2.4
Name: gradientgrove
Version: 0.1.5.dev1
Summary: Python scripts for teaching and scholarship, under development.  Currently contains scripts that allow the creation of both documents and slideshow from a single Markdown file, or a Mkdocs project.  Create a markdown file with mkdocs-style admonitions, compile to html, revealjs, latex, and beamer outputs.
Author-email: Stephen Flood <stephen.flood@bridgew.edu>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://gradientgrove.com
Project-URL: Issues, https://gradientgrove.com
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markdown
Requires-Dist: mkdocs
Requires-Dist: pymdown-extensions
Dynamic: license-file

# gradientgrove

Local Python scripts for reusable Markdown, LaTeX, and publishing workflows.

## Command-line help

Both scripts use `argparse`, so pass `-h` or `--help` to see the current usage and options:

```bash
gradientgrove-publish --help
gradientgrove-latex-to-markdown --help
```

After installation, setuptools exposes the console scripts shown above. When running from a source checkout instead of an installed package, use the equivalent module form and prefix commands with `PYTHONPATH=src`:

```bash
PYTHONPATH=src python -m gradientgrove.publish --help
PYTHONPATH=src python -m gradientgrove.markdown_ast --help
```

## Markdown Syntax

- Standard Mkdocs/python-markdown syntax
- Several additional fences, with behavior dependent on output format
    - Contents of `frame` become slides in revealjs/beamer output.  Contents of `pause` are revealed when advancing. 
    - A page break is inserted before and after the contents of `page`
    - A `newpage` environment with no contents inserts a pagebreak. 
- You cannot put (sub)*section divisions inside a `frame`

| environment | article (html/pdf) | slides (revealjs/beamer) | 
| ------- | ------ | ------ | 
| `frame`, `pause` | ignored | yes | 
| `newpage`, `page`, `vspace`, `vfill` | yes | ignored | 
| `exercise`, `answer` | yes | yes | 
| `theorem`, `definition` | yes | yes | 

```
---
title : "My Document"
author: "Firstname Lastname"
---

# Background

!!! note 
    Standard MkDocs/Python Markdown admonitions work

??? info
    Collapsable admonitions work too

# Slideshows

!!! frame "Frame Title"

    Frame contents go here

    !!! pause
        Displayed when advanced
    
!!! exercise
    You can put exercises between frames

??? answer
    And you can put answers too. 

    Answers are **excluded** from handout mode

!!! frame
    You can put the next frame here

!!! page
    !!! exercise 
        You can also make a worksheet with spaces
    
    !!! vfill

    !!! exercise
        Another exercise
    
    !!! vfill

# Mathematics environments

!!! definition 
    Definitions work

!!! theorem
    Theorems too

Currently supported environments are hardcoded into the template, particularly for latex output.
Eventually there should be a more dynamic solution. 
```


## Publishing Markdown documents

`gradientgrove.markdown_publish` converts Markdown files into HTML, Reveal.js slides, LaTeX articles, LaTeX handouts, and Beamer slides.

Basic usage:

```bash
gradientgrove-publish [path] [options]
```

The optional `path` can be:

- omitted: treat the current directory as a MkDocs project, merge Markdown pages from `mkdocs.yml` navigation, write all generated outputs in `.publish_cache`, and package them into one `.publish_cache/mkdocs.zip` file;
- a Markdown file: convert that single file, write all generated outputs in `.publish_cache` beside it, and package them into one ZIP file there;
- a directory: recursively convert every `*.md` file below that directory, write all generated outputs in that directory's `.publish_cache`, and package them into one ZIP file there.

If no output option is supplied, the script generates the base HTML document by default.

Available output options:

- HTML output
    - `--base` Numbered base HTML document. 
    - `--handout`  Numbered HTML handout with `answer` environments omitted. 
    - `--revealjs`  Numbered Reveal.js slide deck. 
    - `--html`  All HTML outputs: base, handout, and Reveal.js. 

- LaTeX and PDF have similar options to output latex source and to compile it using with `lualatex`: `--tex`, `--tex_handout` , `--beamer` . 

- `--all` generates all output formats, including HTML, LaTeX article, LaTeX handout, and Beamer outputs. 

- `--version VERSION`, `-v VERSION`  Add the version string to generated output filenames and ZIP names. 

- `--no-mkdocs-page-zip`  In no-argument MkDocs mode, only include the merged MkDocs output in `.publish_cache/mkdocs.zip`. 

- `-h`, `--help`  Show command help and exit. 

Examples:

```bash
# Merge a MkDocs project from the current directory, generate every output format,
# and package generated HTML, TeX, and PDF files in .publish_cache/mkdocs.zip.
gradientgrove-publish --all

# Build and package only the merged MkDocs output.
gradientgrove-publish --no-mkdocs-page-zip


# Generate the default base HTML for a single Markdown file in .publish_cache.
gradientgrove-publish examples/testfile.md

# Generate all HTML variants for one file.
gradientgrove-publish examples/testfile.md --html

# Generate a versioned Beamer deck and TeX handout.
gradientgrove-publish examples/testfile.md --beamer --tex_handout --version week1
```

Generated HTML, TeX, and PDF outputs are written in `.publish_cache` and packaged together into one ZIP file. LaTeX outputs require `lualatex` on `PATH` if you want the compilation step to produce PDFs.

## Converting LaTeX to Markdown

`gradientgrove-latex-to-markdown` converts a LaTeX file to Markdown using the package's LaTeX parser.

Basic usage:

```bash
gradientgrove-latex-to-markdown input.tex [output.md]
```

If `output.md` is omitted, the command writes beside the input file with a `.md` suffix. By default, Beamer `\mode<...>{...}` blocks are normalized before parsing; pass `--no-dump-modes` to skip that preprocessing step.

