feat: Move el2org to docs subcommand (#388)

* feat: Move el2org to docs subcommand

* changelog

* docs: update interface

* test: Add docs tests

* feat: Require 28.1 for el2org

* test: Restore vc status after test

* fix: pr no

Author: jcs090218

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

cmds/core/docs.js

@@ -17,26 +17,22 @@
 
 "use strict";
 
-exports.command = ['docs [names..]', 'doc [names..]'];
+exports.command = ['docs <generator>', 'doc <generator>'];
 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 <generator> [options..]`)
+    .commandDir('../docs/')
+    .demandCommand();
+
+  /* XXX: Configure only in the menu. */
+  if (UTIL.cmd_count() == 1) {
+    yargs.positional(
+      '<generator>', {
+        description: 'type of the generator',
+      });
+  }
+}
+
+exports.handler = async (argv) => { };

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 <https://www.gnu.org/licenses/>.
+ */
+
+"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));
+};

docs/content/Getting-Started/Basic-Usage/_index.en.md

@@ -38,7 +38,7 @@ Commands:
   compile [names..]          Byte-compile `.el' files
   create <type>              Create a new elisp project
   docker <version> [args..]  Launch specified Emacs version in a Docker container
-  docs [names..]             Build documentation                                                                                                                                                   [aliases: doc]
+  docs <generator>           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]

docs/content/Getting-Started/Basic-Usage/_index.zh-tw.md

@@ -35,7 +35,7 @@ Commands:
   compile [names..]          Byte-compile `.el' files
   create <type>              Create a new elisp project
   docker <version> [args..]  Launch specified Emacs version in a Docker container
-  docs [names..]             Build documentation                                                                                                                                                   [aliases: doc]
+  docs <generator>           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]

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

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

lisp/core/docs.el lisp/docs/el2org.ellisp/core/docs.el renamed to 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

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([

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/