diff --git a/CHANGELOG.md b/CHANGELOG.md index b0d7a0da..67326e36 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 ([#388](../../pull/388)) ## 0.12.x > Released Dec 02, 2025 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/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] 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 92% rename from lisp/core/docs.el rename to lisp/docs/el2org.el index dd4cd83b..7cf9f0e4 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: ;; @@ -23,6 +23,11 @@ (locate-dominating-file dir "_prepare.el")) nil t)) +;; +;;; Flags + +(eask-command-check "28.1") + ;; ;;; Externals @@ -72,4 +77,4 @@ (eask-info "(No elisp source can be read)") (eask-help "core/docs"))))) -;;; core/docs.el ends here +;;; docs/el2org.el ends here diff --git a/test/jest/local.test.js b/test/jest/local.test.js index 08f6152d..8c3d505b 100644 --- a/test/jest/local.test.js +++ b/test/jest/local.test.js @@ -79,6 +79,14 @@ describe("local", () => { }); }); + describe("Documentation", () => { + it("docs el2org", async () => { + if (cmp(await emacsVersion(), "28.1") == 1) { + await ctx.runEask("docs el2org"); + } + }); + }); + describe("Development", () => { beforeAll(async () => { await ctx.runEask("install-deps", { timeout: 40000 }); @@ -139,6 +147,9 @@ describe("local", () => { "recipes", // from generate recipes ".gitignore", // from generate ignore elisp ); + + // restore original .gitignore + await ctx.run("git restore ."); }); it.each([ 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/