🆙 Upgrade Jupyter Books in myst init (#1223)

.changeset/thick-fans-hear.md

@@ -0,0 +1,5 @@
+---
+"myst-cli": minor
+---
+
+Add Jupyter Book upgrade feature

packages/myst-cli/package.json

@@ -82,13 +82,13 @@
     "myst-spec": "^0.0.5",
     "myst-spec-ext": "^1.4.7",
     "myst-templates": "^1.0.19",
-    "myst-toc": "^0.1.1",
     "myst-to-docx": "^1.0.10",
     "myst-to-jats": "^1.0.26",
     "myst-to-md": "^1.0.11",
     "myst-to-tex": "^1.0.30",
     "myst-to-typst": "^0.0.17",
     "myst-transforms": "^1.3.18",
+    "myst-toc": "^0.1.1",
     "nanoid": "^4.0.0",
     "nbtx": "^0.2.3",
     "node-fetch": "^3.3.1",
@@ -105,7 +105,8 @@
     "vfile": "^5.3.5",
     "which": "^3.0.1",
     "ws": "^8.9.0",
-    "xml-js": "^1.6.11"
+    "xml-js": "^1.6.11",
+    "zod": "^3.23.8"
   },
   "devDependencies": {
     "@jupyterlab/nbformat": "3.5.2",

packages/myst-cli/src/build/index.ts

@@ -1,7 +1,6 @@
 export * from './build.js';
 export * from './clean.js';
 export * from './docx/index.js';
-export * from './init.js';
 export * from './pdf/index.js';
 export * from './site/index.js';
 export * from './tex/index.js';

packages/myst-cli/src/build/utils/index.ts

@@ -5,4 +5,3 @@ export * from './getFileContent.js';
 export * from './localArticleExport.js';
 export * from './resolveAndLogErrors.js';
 export * from './bibtex.js';
-export * from './github.js';

packages/myst-cli/src/index.ts

@@ -1,6 +1,7 @@
 export * from './build/index.js';
 export * from './cli/index.js';
 export * from './config.js';
+export * from './init/index.js';
 export * from './frontmatter.js';
 export * from './plugins.js';
 export * from './process/index.js';

packages/myst-cli/src/build/gh-actions/index.ts → packages/myst-cli/src/init/gh-actions/index.ts

@@ -4,8 +4,8 @@ import inquirer from 'inquirer';
 import chalk from 'chalk';
 import type { ISession } from 'myst-cli-utils';
 import { writeFileToFolder } from 'myst-cli-utils';
-import { getGithubUrl } from '../utils/github.js';
-import { checkFolderIsGit, checkAtGitRoot } from '../utils/git.js';
+import { getGithubUrl } from '../../utils/github.js';
+import { checkFolderIsGit, checkAtGitRoot } from '../../utils/git.js';
 
 function createGithubPagesAction({
   defaultBranch = 'main',

packages/myst-cli/src/init/index.ts

@@ -0,0 +1 @@
+export * from './init.js';

packages/myst-cli/src/build/init.ts → packages/myst-cli/src/init/init.ts

@@ -2,16 +2,19 @@ import fs from 'node:fs';
 import path from 'node:path';
 import yaml from 'js-yaml';
 import { v4 as uuid } from 'uuid';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
 import { defaultConfigFile, loadConfig, writeConfigs } from '../config.js';
 import { loadProjectFromDisk } from '../project/load.js';
 import { selectors } from '../store/index.js';
 import type { ISession } from '../session/types.js';
-import inquirer from 'inquirer';
-import chalk from 'chalk';
-import { startServer } from './site/start.js';
+import { startServer } from '../build/site/start.js';
 import { githubCurvenoteAction, githubPagesAction } from './gh-actions/index.js';
-import { getGithubUrl } from './utils/github.js';
-import { checkFolderIsGit } from './utils/git.js';
+import { getGithubUrl } from '../utils/github.js';
+import { checkFolderIsGit } from '../utils/git.js';
+import { upgradeJupyterBook } from './jupyter-book/upgrade.js';
+import { fsExists } from '../utils/fsExists.js';
+
 const VERSION_CONFIG = '# See docs at: https://mystmd.org/guide/frontmatter\nversion: 1\n';
 
 function createProjectConfig({ github }: { github?: string } = {}) {
@@ -127,24 +130,61 @@ export async function init(session: ISession, opts: InitOptions) {
       await writeConfigs(session, '.', { siteConfig, projectConfig });
     }
   } else {
-    // If no config is present, write it explicitly to include comments.
-    const configFile = defaultConfigFile(session, '.');
-    let configData: string;
-    let configDoc: string;
-    if (site && !project) {
-      configData = `${VERSION_CONFIG}${SITE_CONFIG}`;
-      configDoc = 'site';
-    } else if (project && !site) {
-      configData = `${VERSION_CONFIG}${createProjectConfig({ github })}`;
-      configDoc = 'project';
-    } else {
-      configData = `${VERSION_CONFIG}${createProjectConfig({ github })}${SITE_CONFIG}`;
-      configDoc = 'project and site';
+    // Is this a Jupyter Book?
+    let didUpgrade = false;
+    if (await fsExists('_config.yml')) {
+      const configFile = defaultConfigFile(session, '.');
+      const promptUpgrade = await inquirer.prompt([
+        {
+          name: 'upgrade',
+          message: [
+            `📘 Found a legacy Jupyter Book. To proceed, myst needs to perform an upgrade which will:
+`,
+            chalk.dim(`‣ Upgrade any Sphinx-style glossaries to MyST-style glossaries
+‣ Upgrade any case-insensitive admonition names to lowercase (${chalk.blue('Note')} → ${chalk.blue('note')})
+‣ Migrate configuration from ${chalk.blue('_config.yml')} and (if applicable) ${chalk.blue('_toc.yml')} files
+‣ Rename any modified or unneeded files so that they are hidden
+
+`),
+            `Are you willing to proceed?`,
+          ].join(''),
+          type: 'confirm',
+          default: true,
+        },
+      ]);
+      if (!promptUpgrade.upgrade) {
+        return;
+      }
+      session.log.info(`💾 Writing new config file: ${chalk.blue(path.resolve(configFile))}`);
+      try {
+        await upgradeJupyterBook(session, configFile);
+        didUpgrade = true;
+      } catch (err) {
+        session.log.error(`❌ An error occurred during Jupyter Book upgrade:\n\n${err}\n\n`);
+        session.log.warn(`Ignoring Jupyter Book configuration!`);
+      }
+    }
+    // Otherwise, write some default configs
+    if (!didUpgrade) {
+      // If no config is present, write it explicitly to include comments.
+      const configFile = defaultConfigFile(session, '.');
+      let configData: string;
+      let configDoc: string;
+      if (site && !project) {
+        configData = `${VERSION_CONFIG}${SITE_CONFIG}`;
+        configDoc = 'site';
+      } else if (project && !site) {
+        configData = `${VERSION_CONFIG}${createProjectConfig({ github })}`;
+        configDoc = 'project';
+      } else {
+        configData = `${VERSION_CONFIG}${createProjectConfig({ github })}${SITE_CONFIG}`;
+        configDoc = 'project and site';
+      }
+      session.log.info(
+        `💾 Writing new ${configDoc} config file: ${chalk.blue(path.resolve(configFile))}`,
+      );
+      fs.writeFileSync(configFile, configData);
     }
-    session.log.info(
-      `💾 Writing new ${configDoc} config file: ${chalk.blue(path.resolve(configFile))}`,
-    );
-    fs.writeFileSync(configFile, configData);
   }
   if (writeTOC) {
     await loadConfig(session, '.');