From 8732b1566a2513a7b5d517e3131e07279248ffaa Mon Sep 17 00:00:00 2001 From: JenChieh Date: Sat, 24 Jan 2026 03:24:19 +0800 Subject: [PATCH 1/7] feat: Move el2org to docs subcommand --- cmds/core/docs.js | 38 ++++++++--------- cmds/docs/el2org.js | 42 +++++++++++++++++++ .../Commands-and-options/_index.en.md | 8 ++-- .../Commands-and-options/_index.zh-tw.md | 8 ++-- lisp/{core/docs.el => docs/el2org.el} | 4 +- 5 files changed, 71 insertions(+), 29 deletions(-) create mode 100644 cmds/docs/el2org.js rename lisp/{core/docs.el => docs/el2org.el} (94%) diff --git a/cmds/core/docs.js b/cmds/core/docs.js index 9fd90676..7bb2b9bf 100644 --- a/cmds/core/docs.js +++ b/cmds/core/docs.js @@ -17,26 +17,22 @@ "use strict"; -exports.command = ['docs [names..]', 'doc [names..]']; +exports.command = ['docs ', 'doc ']; exports.desc = 'Build documentation'; -exports.builder = yargs => yargs - .positional( - '[names..]', { - description: 'specify source files to scan', - type: 'array', - }) - .options({ - 'destination': { - description: 'optional output destination', - requiresArg: true, - alias: 'dest', - type: 'string', - group: TITLE_CMD_OPTION, - }, - }); +exports.builder = function (yargs) { + yargs.usage(`${exports.desc} -exports.handler = async (argv) => { - await UTIL.e_call(argv, 'core/docs' - , argv.names - , UTIL.def_flag(argv.dest, '--dest', argv.dest)); -}; +Usage: eask docs [options..]`) + .commandDir('../docs/') + .demandCommand(); + + /* XXX: Configure only in the menu. */ + if (UTIL.cmd_count() == 1) { + yargs.positional( + '', { + description: 'type of the generator', + }); + } +} + +exports.handler = async (argv) => { }; diff --git a/cmds/docs/el2org.js b/cmds/docs/el2org.js new file mode 100644 index 00000000..a072cb6f --- /dev/null +++ b/cmds/docs/el2org.js @@ -0,0 +1,42 @@ +/** + * Copyright (C) 2024-2026 the Eask authors. + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 3, or (at your option) + * any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + +"use strict"; + +exports.command = ['el2org [names..]', ]; +exports.desc = 'Build documentation with el2org'; +exports.builder = yargs => yargs + .positional( + '[names..]', { + description: 'specify source files to scan', + type: 'array', + }) + .options({ + 'destination': { + description: 'optional output destination', + requiresArg: true, + alias: 'dest', + type: 'string', + group: TITLE_CMD_OPTION, + }, + }); + +exports.handler = async (argv) => { + await UTIL.e_call(argv, 'docs/el2org' + , argv.names + , UTIL.def_flag(argv.dest, '--dest', argv.dest)); +}; diff --git a/docs/content/Getting-Started/Commands-and-options/_index.en.md b/docs/content/Getting-Started/Commands-and-options/_index.en.md index 981ab4d3..4bc1a9fe 100644 --- a/docs/content/Getting-Started/Commands-and-options/_index.en.md +++ b/docs/content/Getting-Started/Commands-and-options/_index.en.md @@ -349,12 +349,12 @@ eask [GLOBAL-OPTIONS] loc [FILES..] Commands used to build documentation site. -## 🔍 eask docs +## 🔍 eask docs el2org -Build documentation. +Build documentation with [el2org][]. ```sh -eask [GLOBAL-OPTIONS] docs [NAMES..] +eask [GLOBAL-OPTIONS] docs el2org [NAMES..] ``` # 🚩 Execution @@ -1178,6 +1178,8 @@ Do not use a proxy for any URL matching pattern. [GitLab Runner]: https://docs.gitlab.com/runner/ [Travis CI]: https://www.travis-ci.com/ +[el2org]: https://github.com/tumashu/el2org + [ert]: https://www.gnu.org/software/emacs/manual/html_node/ert/ [ert-runner]: https://github.com/rejeep/ert-runner.el [buttercup]: https://github.com/jorgenschaefer/emacs-buttercup diff --git a/docs/content/Getting-Started/Commands-and-options/_index.zh-tw.md b/docs/content/Getting-Started/Commands-and-options/_index.zh-tw.md index 60a48db6..37992380 100644 --- a/docs/content/Getting-Started/Commands-and-options/_index.zh-tw.md +++ b/docs/content/Getting-Started/Commands-and-options/_index.zh-tw.md @@ -344,12 +344,12 @@ eask [GLOBAL-OPTIONS] loc [FILES..] 用於建立文檔站點的命令。 -## 🔍 eask docs +## 🔍 eask docs el2org -建置文檔。 +使用 [el2org][] 建置文檔。 ```sh -eask [GLOBAL-OPTIONS] docs [NAMES..] +eask [GLOBAL-OPTIONS] docs el2org [NAMES..] ``` # 🚩 執行 @@ -1163,6 +1163,8 @@ eask --proxy "localhost:8888" [COMMAND] [GitLab Runner]: https://docs.gitlab.com/runner/ [Travis CI]: https://www.travis-ci.com/ +[el2org]: https://github.com/tumashu/el2org + [ert]: https://www.gnu.org/software/emacs/manual/html_node/ert/ [ert-runner]: https://github.com/rejeep/ert-runner.el [buttercup]: https://github.com/jorgenschaefer/emacs-buttercup diff --git a/lisp/core/docs.el b/lisp/docs/el2org.el similarity index 94% rename from lisp/core/docs.el rename to lisp/docs/el2org.el index dd4cd83b..33fa98b7 100644 --- a/lisp/core/docs.el +++ b/lisp/docs/el2org.el @@ -1,4 +1,4 @@ -;;; core/docs.el --- Build documentation -*- lexical-binding: t; -*- +;;; docs/el2org.el --- Build documentation with el2org -*- lexical-binding: t; -*- ;;; Commentary: ;; @@ -72,4 +72,4 @@ (eask-info "(No elisp source can be read)") (eask-help "core/docs"))))) -;;; core/docs.el ends here +;;; docs/el2org.el ends here From b44152b39edfd564ceaf2229313c1ff06f95d745 Mon Sep 17 00:00:00 2001 From: JenChieh Date: Sat, 24 Jan 2026 03:26:27 +0800 Subject: [PATCH 2/7] changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b0d7a0da..45929dcb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how * fix(lisp/emacs): Respect Eask file settings when possible ([`1b5aaa1`](../../commit/1b5aaa121b5d6a39e3a0664006fc10a4b22c2e84)) * fix(lisp): Let buttercup tests handle exit code themselves ([#385](../../pull/385)) * fix(lisp): Set up paths regardless of the working environment ([#386](../../pull/386)) +* feat(cmds): Move `el2org` to docs subcommand ([#387](../../pull/387)) ## 0.12.x > Released Dec 02, 2025 From 4c457a4aa3f8cb19070d95691412d5819c6b4d2c Mon Sep 17 00:00:00 2001 From: JenChieh Date: Sat, 24 Jan 2026 03:39:45 +0800 Subject: [PATCH 3/7] docs: update interface --- docs/content/Getting-Started/Basic-Usage/_index.en.md | 2 +- docs/content/Getting-Started/Basic-Usage/_index.zh-tw.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/Getting-Started/Basic-Usage/_index.en.md b/docs/content/Getting-Started/Basic-Usage/_index.en.md index 1a88256d..f4f9e965 100644 --- a/docs/content/Getting-Started/Basic-Usage/_index.en.md +++ b/docs/content/Getting-Started/Basic-Usage/_index.en.md @@ -38,7 +38,7 @@ Commands: compile [names..] Byte-compile `.el' files create Create a new elisp project docker [args..] Launch specified Emacs version in a Docker container - docs [names..] Build documentation [aliases: doc] + docs Build documentation [aliases: doc] emacs [args..] Execute emacs with the appropriate environment eval [form] Evaluate lisp form with a proper PATH path [patterns..] Print the PATH (exec-path) from workspace [aliases: exec-path] diff --git a/docs/content/Getting-Started/Basic-Usage/_index.zh-tw.md b/docs/content/Getting-Started/Basic-Usage/_index.zh-tw.md index 63f675cf..2bae45ee 100644 --- a/docs/content/Getting-Started/Basic-Usage/_index.zh-tw.md +++ b/docs/content/Getting-Started/Basic-Usage/_index.zh-tw.md @@ -35,7 +35,7 @@ Commands: compile [names..] Byte-compile `.el' files create Create a new elisp project docker [args..] Launch specified Emacs version in a Docker container - docs [names..] Build documentation [aliases: doc] + docs Build documentation [aliases: doc] emacs [args..] Execute emacs with the appropriate environment eval [form] Evaluate lisp form with a proper PATH path [patterns..] Print the PATH (exec-path) from workspace [aliases: exec-path] From 2749b234a0b0732ad60ba9c196c0055246880c46 Mon Sep 17 00:00:00 2001 From: JenChieh Date: Sat, 24 Jan 2026 03:53:56 +0800 Subject: [PATCH 4/7] test: Add docs tests --- test/jest/local.test.js | 6 ++++++ test/jest/local/.gitignore | 17 +++++++++++++++++ 2 files changed, 23 insertions(+) create mode 100644 test/jest/local/.gitignore diff --git a/test/jest/local.test.js b/test/jest/local.test.js index 08f6152d..e3eee675 100644 --- a/test/jest/local.test.js +++ b/test/jest/local.test.js @@ -79,6 +79,12 @@ describe("local", () => { }); }); + describe("Documentation", () => { + it("docs el2org", async () => { + await ctx.runEask("docs el2org"); + }); + }); + describe("Development", () => { beforeAll(async () => { await ctx.runEask("install-deps", { timeout: 40000 }); diff --git a/test/jest/local/.gitignore b/test/jest/local/.gitignore new file mode 100644 index 00000000..a831df3f --- /dev/null +++ b/test/jest/local/.gitignore @@ -0,0 +1,17 @@ +# ignore these directories +/.git +/recipes + +# ignore generated files +*.elc + +# eask packages +.eask/ +dist/ + +# packaging +*-autoloads.el +*-pkg.el + +# Documentation generation tests +docs/ From 8c0333c3a93ef2018eb37e4aebb0200bc6f1b632 Mon Sep 17 00:00:00 2001 From: JenChieh Date: Sat, 24 Jan 2026 04:09:33 +0800 Subject: [PATCH 5/7] feat: Require 28.1 for el2org --- lisp/docs/el2org.el | 5 +++++ test/jest/local.test.js | 4 +++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/lisp/docs/el2org.el b/lisp/docs/el2org.el index 33fa98b7..7cf9f0e4 100644 --- a/lisp/docs/el2org.el +++ b/lisp/docs/el2org.el @@ -23,6 +23,11 @@ (locate-dominating-file dir "_prepare.el")) nil t)) +;; +;;; Flags + +(eask-command-check "28.1") + ;; ;;; Externals diff --git a/test/jest/local.test.js b/test/jest/local.test.js index e3eee675..109c832f 100644 --- a/test/jest/local.test.js +++ b/test/jest/local.test.js @@ -81,7 +81,9 @@ describe("local", () => { describe("Documentation", () => { it("docs el2org", async () => { - await ctx.runEask("docs el2org"); + if (cmp(await emacsVersion(), "28.1") == 1) { + await ctx.runEask("docs el2org"); + } }); }); From 12a3c43fe4827ae00f01ea4c01d9a0a0cc9d8f16 Mon Sep 17 00:00:00 2001 From: JenChieh Date: Sat, 24 Jan 2026 04:18:29 +0800 Subject: [PATCH 6/7] test: Restore vc status after test --- test/jest/local.test.js | 3 +++ 1 file changed, 3 insertions(+) diff --git a/test/jest/local.test.js b/test/jest/local.test.js index 109c832f..8c3d505b 100644 --- a/test/jest/local.test.js +++ b/test/jest/local.test.js @@ -147,6 +147,9 @@ describe("local", () => { "recipes", // from generate recipes ".gitignore", // from generate ignore elisp ); + + // restore original .gitignore + await ctx.run("git restore ."); }); it.each([ From 1f57c3879b17d4ebcaca5a951fdc6190c099b0fb Mon Sep 17 00:00:00 2001 From: JenChieh Date: Sat, 24 Jan 2026 04:20:38 +0800 Subject: [PATCH 7/7] fix: pr no --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 45929dcb..67326e36 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,7 +13,7 @@ Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how * fix(lisp/emacs): Respect Eask file settings when possible ([`1b5aaa1`](../../commit/1b5aaa121b5d6a39e3a0664006fc10a4b22c2e84)) * fix(lisp): Let buttercup tests handle exit code themselves ([#385](../../pull/385)) * fix(lisp): Set up paths regardless of the working environment ([#386](../../pull/386)) -* feat(cmds): Move `el2org` to docs subcommand ([#387](../../pull/387)) +* feat(cmds): Move `el2org` to docs subcommand ([#388](../../pull/388)) ## 0.12.x > Released Dec 02, 2025