executablebooks / mystmd

Command line tools for working with MyST Markdown.
https://mystmd.org/guide
MIT License
172 stars 50 forks source link

:pen: Add support for whitelabelling to MyST CLI #1368

Open agoose77 opened 2 days ago

agoose77 commented 2 days ago

The current plan for Jupyter Book is to have it be a thin white-labelled distribution of MyST-MD. The intention here is to avoid having to maintain a separate application with its own release cadence. Instead, we'll just re-skin MyST whilst making it clear that Jupyter Book is MyST.

See also https://github.com/executablebooks/jupyter-book-myst/issues/3

This PR suggests one way to do this, by reading from the environment. Using this approach will require us to be careful in how we write our error messages. I added four functions:

These each return default values unless the corresponding

are set.

N.B. we probably could have these be static and read the env var at import time ... but I don't know if that's a standard pattern.

An example using Jupyter Book:

❯ MYSTMD_HELP_URL="https://jupyterbook.org" MYSTMD_BINARY_NAME="jupyter book" MYSTMD_READABLE_NAME="Jupyter Book (myst)" npx myst init

Welcome to the Jupyter Book (myst) CLI! 🎉 🚀

jupyter book init walks you through creating a myst.yml file.

You can use Jupyter Book (myst) to:

 - create interactive websites from markdown and Jupyter Notebooks 📈
 - build & export professional PDFs and Word documents 📄

Learn more about this CLI and MyST Markdown at: https://jupyterbook.org

✅ .gitignore exists and already ignores Jupyter Book (myst) outputs
✅ Project already initialized with config file: myst.yml
✅ Site already initialized with config file: myst.yml

? Would you like to run jupyter book start now? (Y/n)

This PR also adds a whitelabelling indicator to --help:

❯ MYSTMD_HELP_URL="https://jupyterbook.org" MYSTMD_BINARY_NAME="jupyter book" MYSTMD_READABLE_NAME="Jupyter Book (myst)" npx myst --help
Usage: myst [options] [command]

Jupyter Book (myst) is powered by MyST-MD. See
https://mystmd.org for more information.

Options:
  -v, --version               Print the current version of Jupyter Book (myst)
  -d, --debug                 Log out any errors to the console
  -h, --help                  display help for command

Commands:
  init [options]              Initialize a Jupyter Book (myst) project in the current directory
  build [options] [files...]  Build PDF, LaTeX, Word and website exports from MyST files
  start [options]             Start the current project as a website
  clean [options] [files...]  Remove exports, temp files and installed templates
  templates                   List and download templates

Closes https://github.com/executablebooks/mystmd/issues/1365

agoose77 commented 2 days ago

@choldgraf pinging you for thoughts on this approach, too.