Customise the binary name in the CLI?

[agoose77]

We haven't formally decided what the Jupyter Book CLI looks like yet, but we do know that the Jupyter Book CLI should be either an alias or an extension of the myst CLI, i.e. any command that the CLI suggests to the user should work with Jupyter Book e.g. myst foo -> jupyter book foo. Formally, a mathematical non-strict superset.

An alternative is to literally not ship a binary, and use myst. I worry that this is a step too far (confusing users, and making it hard to guess the command) but I am not entirely against it.

Crucially, I feel that jupyter book and myst should be interchangeable for all the commands that MyST supports, so users can switch between the two.

There are some aspects to this UX that we want to (in my view) balance:

1. Avoid confusion when running jupyter book and seeing `myst" in the CLI output
2. Avoid hiding the fact that Jupyter Book runs on MyST

We can see the problem if we run alias jupyter-book=myst

❯ alias jupyter-book=myst
❯ jupyter-book

Welcome to the MyST Markdown CLI!! 🎉 🚀

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

You can use 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://mystmd.org

✅ .gitignore exists and already ignores MyST outputs
💾 Writing new project and site config file: myst.yml

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

I think a sweet spot here is to allow Jupyter Book to customise the MyST binary such that it assumes a new name. This could be (and probably should be) and environment variable that is set by Jupyter Book before it launches, e.g.

import os

os.environ['MYSTMD_PROGRAM_NAME'] = "Jupyter Book (via MyST)"
os.environ['MYSTMD_BINARY_NAME'] = "jupyter book"

os.exec(...)

If we implemented this, the above example might look something like

❯ alias jupyter-book=myst
❯ jupyter-book

Welcome to the Jupyter Book (via MyST) CLI!! 🎉 🚀

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

You can use jupyter book 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://mystmd.org

✅ .gitignore exists and already ignores MyST outputs
💾 Writing new project and site config file: myst.yml

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

I'd welcome thoughts from the rest of the MyST team on alternatives / other aspects to consider (and also @choldgraf).

[rowanc1]

We are doing something similar for the update install, which suggests PIP rather than NPM if you are using it through the Python CLI.