feat: Add docs command (#245)

* feat: Add docs command

* changelog

* fix doc

CHANGELOG.md

@@ -25,6 +25,7 @@ Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how
 * feat(test): Add built-in `ecukes` test command (#236)
 * fix: Don't pollute outer programs (#239)
 * feat(generate/test): Add commands to setup test files (#243)
+* feat: Add `docs` command (#245)
 
 ## 0.9.x
 > Released Nov 17, 2023

cmds/core/docs.js

@@ -0,0 +1,42 @@
+/**
+ * Copyright (C) 2024 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 = ['docs [names..]', 'doc [names..]'];
+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.handler = async (argv) => {
+  await UTIL.e_call(argv, 'core/docs'
+                    , argv.names
+                    , UTIL.def_flag(argv.dest, '--dest', argv.dest));
+};

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

@@ -38,6 +38,7 @@ Commands:
   compile [names..]          Byte compile all Emacs Lisp files in the package
   create <type>              Create a new elisp project
   docker <version> [args..]  Launch specified Emacs version in a Docker container
+  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]

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

@@ -5,7 +5,7 @@ weight: 250
 
 Eask 的 CLI 功能齊全但易於使用，即使對於那些使用命令行的經驗非常有限的人也是如此。
 
-以下是您在開發 Eask 項目時將使用的最常用命令的說明。 請參閱 
+以下是您在開發 Eask 項目時將使用的最常用命令的說明。 請參閱
 [命令和選項](https://emacs-eask.github.io/Getting-Started/Commands-and-options/)
 以全面了解 Eask 的 CLI。
 
@@ -35,6 +35,7 @@ Commands:
   compile [names..]          Byte compile all Emacs Lisp files in the package
   create <type>              Create a new elisp project
   docker <version> [args..]  Launch specified Emacs version in a Docker container
+  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]

docs/content/Getting-Started/Commands-and-options/_index.en.md

@@ -229,7 +229,7 @@ Print the load path containing the dependencies of the current project.
 $ eask [GLOBAL-OPTIONS] load-path [PATTERNS..]
 ```
 
-Optionally, you can pass in `[PATTERNS..]` to perform the search. 
+Optionally, you can pass in `[PATTERNS..]` to perform the search.
 
 ## 🔍 eask files
 
@@ -300,6 +300,18 @@ Print LOC information.
 $ eask [GLOBAL-OPTIONS] loc [FILES..]
 ```
 
+# 🚩 Documentation
+
+Commands used to build documentation site.
+
+## 🔍 eask docs
+
+Build documentation.
+
+```sh
+$ eask [GLOBAL-OPTIONS] docs [NAMES..]
+```
+
 # 🚩 Execution
 
 Commands allow you to execute on top of the Eask core.
@@ -587,8 +599,8 @@ $ eask [GLOBAL-OPTIONS] generate workflow travis-ci [--file]
 
 # 🚩 Linking
 
-Link between this package and a dependency on the local filesystem. A linked 
-dependency avoids the need to download a dependency from a remote archive. The 
+Link between this package and a dependency on the local filesystem. A linked
+dependency avoids the need to download a dependency from a remote archive. The
 package linked to must either have a `Eask`-file or a `-pkg.el`-file.
 
 ## 🔍 eask link add

docs/content/Getting-Started/Commands-and-options/_index.zh-tw.md

@@ -296,6 +296,18 @@ $ eask [GLOBAL-OPTIONS] concate [FILES..]
 $ eask [GLOBAL-OPTIONS] loc [FILES..]
 ```
 
+# 🚩 文件
+
+用於建立文檔站點的命令。
+
+## 🔍 eask docs
+
+建置文檔。
+
+```sh
+$ eask [GLOBAL-OPTIONS] docs [NAMES..]
+```
+
 # 🚩 執行
 
 指令允許執行在 Eask 核心之上。

lisp/_prepare.el

@@ -1987,7 +1987,12 @@ variable we use to test validation."
   :group 'eask)
 
 (defcustom eask-dist-path "dist"
-  "Name of default target directory for building packages."
+  "Default path where to place the package artifact."
+  :type 'string
+  :group 'eask)
+
+(defcustom eask-docs-path "docs/public/"
+  "Default path where to place the documentation."
   :type 'string
   :group 'eask)
 

lisp/core/docs.el

@@ -0,0 +1,75 @@
+;;; core/docs.el --- Build documentation  -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;;
+;; Build documentation for your Elisp project,
+;;
+;;   $ eask docs [names..]
+;;
+;;
+;;  Positionals:
+;;
+;;    [names..]         specify files to scan
+;;
+;;  Action options:
+;;
+;;    [destination]     optional output destination
+;;
+
+;;; Code:
+
+(let ((dir (file-name-directory (nth 1 (member "-scriptload" command-line-args)))))
+  (load (expand-file-name "_prepare.el"
+                          (locate-dominating-file dir "_prepare.el"))
+        nil t))
+
+;;
+;;; Externals
+
+(require 'el2org nil t)
+
+;;
+;;; Core
+
+(defun eask-docs--to-html (el-file)
+  "Generate html file from EL-FILE."
+  (interactive)
+  (let* ((filename (file-name-nondirectory el-file))
+         (html-file (expand-file-name (concat (file-name-sans-extension filename)
+                                              ".html")
+                                      eask-docs-path)))
+    (eask-with-verbosity 'debug
+      (el2org-generate-file el-file nil 'html html-file t))))
+
+(eask-start
+  ;; Preparation
+  (eask-with-archives '("gnu" "melpa")
+    (eask-package-install 'el2org))
+
+  ;; Start building...
+  (require 'el2org)
+  (let* ((patterns (eask-args))
+         (files (if patterns (eask-expand-file-specs patterns)
+                  (eask-package-el-files)))
+         (eask-docs-path (or (eask-dest) eask-docs-path)))
+    (cond
+     ;; Files found, do the action!
+     (files
+      (eask-debug "Destination path in %s" eask-docs-path)
+      (ignore-errors (make-directory eask-docs-path t))
+
+      (eask-progress-seq
+       "  - Processing" files "done! ✓" #'eask-docs--to-html)
+      (eask-msg "")
+      (eask-info "Done. (Converted %s file%s)" (length files)
+                 (eask--sinr files "" "s")))
+     ;; Pattern defined, but no file found!
+     (patterns
+      (eask-info "(No files match wildcard: %s)"
+                 (mapconcat #'identity patterns " ")))
+     ;; Default, print help!
+     (t
+      (eask-info "(No elisp source can be read)")
+      (eask-help "core/docs")))))
+
+;;; core/docs.el ends here

lisp/help/core/concat

@@ -0,0 +1,4 @@
+
+💡 You would need to specify the [names..] in order to make concatenation!
+
+    $ eask concat [names..]

lisp/help/core/docs

@@ -0,0 +1,4 @@
+
+💡 You would need to specify the [names..] in order to build documentation!
+
+    $ eask docs [names..]

test/commands/local/run.sh

@@ -42,6 +42,10 @@ eask concat
 #eask loc                       # Only 27.1+
 #eask loc Eask                  # Only 27.1+
 
+# Documentation
+#eask docs                      # Only 28.1+
+#eask docs *.el                 # Only 28.1+
+
 # PATH environment
 eask path
 eask path      bin