From ad09ac44e396f836172849ed20e0fce72a637f91 Mon Sep 17 00:00:00 2001 From: JenChieh Date: Fri, 19 Apr 2024 16:45:07 -0700 Subject: [PATCH 1/3] feat: Add docs command --- cmds/core/docs.js | 42 +++++++++++ .../Getting-Started/Basic-Usage/_index.en.md | 1 + .../Basic-Usage/_index.zh-tw.md | 3 +- .../Commands-and-options/_index.en.md | 18 ++++- .../Commands-and-options/_index.zh-tw.md | 12 +++ lisp/_prepare.el | 7 +- lisp/core/docs.el | 75 +++++++++++++++++++ lisp/help/core/concat | 4 + lisp/help/core/docs | 4 + test/commands/local/run.sh | 4 + 10 files changed, 165 insertions(+), 5 deletions(-) create mode 100644 cmds/core/docs.js create mode 100644 lisp/core/docs.el create mode 100644 lisp/help/core/concat create mode 100644 lisp/help/core/docs diff --git a/cmds/core/docs.js b/cmds/core/docs.js new file mode 100644 index 00000000..5bb15ed9 --- /dev/null +++ b/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 . + */ + +"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)); +}; diff --git a/docs/content/Getting-Started/Basic-Usage/_index.en.md b/docs/content/Getting-Started/Basic-Usage/_index.en.md index 96bc13d9..fcec8cbc 100644 --- a/docs/content/Getting-Started/Basic-Usage/_index.en.md +++ b/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 Create a new elisp project docker [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] 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 d34564c5..71e1de71 100644 --- a/docs/content/Getting-Started/Basic-Usage/_index.zh-tw.md +++ b/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 Create a new elisp project docker [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] 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 b922aab2..bac2925b 100644 --- a/docs/content/Getting-Started/Commands-and-options/_index.en.md +++ b/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 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 25ec3d56..0015b773 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 @@ -296,6 +296,18 @@ $ eask [GLOBAL-OPTIONS] concate [FILES..] $ eask [GLOBAL-OPTIONS] loc [FILES..] ``` +# 🚩 文件 + +用於建立文檔站點的命令。 + +## 🔍 eask docs + +建置文檔。 + +```sh +$ eask [GLOBAL-OPTIONS] docs [NAMES..] +``` + # 🚩 執行 指令允許執行在 Eask 核心之上。 diff --git a/lisp/_prepare.el b/lisp/_prepare.el index 57b5c82c..722fec07 100644 --- a/lisp/_prepare.el +++ b/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) diff --git a/lisp/core/docs.el b/lisp/core/docs.el new file mode 100644 index 00000000..688585a1 --- /dev/null +++ b/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 concatenate +;; +;; 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 diff --git a/lisp/help/core/concat b/lisp/help/core/concat new file mode 100644 index 00000000..a5a79357 --- /dev/null +++ b/lisp/help/core/concat @@ -0,0 +1,4 @@ + +💡 You would need to specify the [names..] in order to make concatenation! + + $ eask concat [names..] diff --git a/lisp/help/core/docs b/lisp/help/core/docs new file mode 100644 index 00000000..c0c7cc30 --- /dev/null +++ b/lisp/help/core/docs @@ -0,0 +1,4 @@ + +💡 You would need to specify the [names..] in order to build documentation! + + $ eask docs [names..] diff --git a/test/commands/local/run.sh b/test/commands/local/run.sh index d530a1db..91863677 100644 --- a/test/commands/local/run.sh +++ b/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 +eask docs *.el + # PATH environment eask path eask path bin From 8d23bbf3938d65568c7a3c3875a0adbf131d88c8 Mon Sep 17 00:00:00 2001 From: JenChieh Date: Fri, 19 Apr 2024 17:03:32 -0700 Subject: [PATCH 2/3] changelog --- CHANGELOG.md | 1 + test/commands/local/run.sh | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8d17e60d..db1bc880 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/test/commands/local/run.sh b/test/commands/local/run.sh index 91863677..86c21229 100644 --- a/test/commands/local/run.sh +++ b/test/commands/local/run.sh @@ -43,8 +43,8 @@ eask concat #eask loc Eask # Only 27.1+ # Documentation -eask docs -eask docs *.el +#eask docs # Only 28.1+ +#eask docs *.el # Only 28.1+ # PATH environment eask path From 50938bb08816815bbf845bdc0dd26e21930729d3 Mon Sep 17 00:00:00 2001 From: JenChieh Date: Fri, 19 Apr 2024 17:04:38 -0700 Subject: [PATCH 3/3] fix doc --- lisp/core/docs.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lisp/core/docs.el b/lisp/core/docs.el index 688585a1..8bc8de57 100644 --- a/lisp/core/docs.el +++ b/lisp/core/docs.el @@ -9,7 +9,7 @@ ;; ;; Positionals: ;; -;; [names..] specify files to concatenate +;; [names..] specify files to scan ;; ;; Action options: ;;