From c470c6a669c395d82247d79fa3be0084727bb8e3 Mon Sep 17 00:00:00 2001 From: YugaEgo Date: Tue, 11 Jan 2022 03:05:37 +0200 Subject: [PATCH] Add ':doc-links' property to specifications Provide control over documentation linked from package page. * elpa-admin.el (elpaa--html-insert-docs, elpaa--build-Info-1): Utilize new property. * README (:doc-links): Usage instructions. --- README | 10 ++++++++++ elpa-admin.el | 51 +++++++++++++++++++++++++++++++-------------------- 2 files changed, 41 insertions(+), 20 deletions(-) diff --git a/README b/README index a0e34ff78c..dd5d9aef41 100644 --- a/README +++ b/README @@ -146,6 +146,16 @@ Name of the documentation file for the package. It can be either an Info file, a Texinfo file, or an Org file. FILE can also be a list of those. +** =:doc-links LINKS= +Allows configuring documentation links for the package page. By +default, if =:doc= specification contains a Texinfo file, then HTML +documentation is generated from it; the link to the generated HTML +file is added to the package page. To disable this behavior, set +=:doc-links= to ~ignore~ or to an association list of the titles and +URLs of an existing documentation. For example: + + (("User Manual" . "https://example.tld/manual.html")) + ** =:make TARGET= Indicates that we should run ~make TARGET~ in order to build some files. This is run before processing =:doc=, so it can be used to generate diff --git a/elpa-admin.el b/elpa-admin.el index 363919d9ab..6c25be5483 100644 --- a/elpa-admin.el +++ b/elpa-admin.el @@ -1449,25 +1449,35 @@ arbitrary code." (concat (file-name-base docfile) ".html")) (defun elpaa--html-insert-docs (pkg-spec) - (let ((docfiles (reverse (plist-get (cdr pkg-spec) :internal--html-docs))) - ;; `html-dir' is relative to the tarball directory, so html - ;; references on mirrors work. It does not include the - ;; package name, so cross references among package docs work. - (html-dir (when elpaa--doc-subdirectory - (file-name-as-directory elpaa--doc-subdirectory)))) - (when (and docfiles html-dir - ;; FIXME: This dir is shared, so it will always exist. - ;; Should we use (expand-file-name pkg html-dir) instead? - (file-readable-p html-dir)) ;; html doc files were built - (insert "
Manual
\n") - (dolist (doc docfiles) - (let ((html-file (concat html-dir (cdr doc)))) - (insert "" - (car doc) - "\n") - ;; FIXME: get link text from info direntry? - )) - (insert "
\n")))) + (let ((doc-links (elpaa--spec-get pkg-spec :doc-links))) + (unless (equal doc-links 'ignore) + (let ((docfiles (or doc-links + (reverse (elpaa--spec-get + pkg-spec :internal--html-docs)))) + ;; `html-dir' is relative to the tarball directory, so + ;; html references on mirrors work. It does not include + ;; the package name, so cross references among package + ;; docs work. + (html-dir (when (and (not doc-links) elpaa--doc-subdirectory) + (file-name-as-directory elpaa--doc-subdirectory)))) + (when (and docfiles + (or doc-links + ;; FIXME: This dir is shared, so it will always + ;; exist. Should we use (expand-file-name pkg + ;; html-dir) instead? + (and html-dir + ;; html doc files were built + (file-readable-p html-dir)))) + (insert "
Documentation
\n") + (dolist (doc docfiles) + (let ((html-file (if doc-links (cdr doc) + (concat html-dir (cdr doc))))) + (insert "" + (car doc) + "\n") + ;; FIXME: get link text from info direntry? + )) + (insert "
\n")))))) (defun elpaa--html-make-pkg (pkg pkg-spec files srcdir) (let* ((name (symbol-name (car pkg))) @@ -2106,7 +2116,8 @@ relative to elpa root." t "makeinfo" "--no-split" docfile "-o" info-file) (message "%s" (buffer-string))) - (when html-dir (elpaa--html-build-doc pkg-spec docfile html-dir)) + (when (and html-dir (not (elpaa--spec-get pkg-spec :doc-links))) + (elpaa--html-build-doc pkg-spec docfile html-dir)) (setq docfile info-file))) -- 2.34.1