diff --git a/full/commondoc/image.lisp b/full/commondoc/image.lisp index 81f5828..4dcb020 100644 --- a/full/commondoc/image.lisp +++ b/full/commondoc/image.lisp @@ -27,11 +27,22 @@ :initarg :height :reader height))) + (defun full-path (relative-path) - (if *current-asdf-system* - (asdf:system-relative-pathname *current-asdf-system* - relative-path) - relative-path)) + (cond + ((str:starts-with-p "asdf:" relative-path) + (destructuring-bind (prefix asdf-system-name path) + (str:split ":" relative-path + :limit 3) + (declare (ignore prefix)) + (asdf:system-relative-pathname asdf-system-name + path))) + (*current-asdf-system* + (asdf:system-relative-pathname *current-asdf-system* + relative-path)) + (t + relative-path))) + (defun make-local-image (relative-path &key width height) (unless (probe-file (full-path relative-path)) diff --git a/full/markdown.lisp b/full/markdown.lisp index a59b7f1..5ff5b5a 100644 --- a/full/markdown.lisp +++ b/full/markdown.lisp @@ -14,6 +14,7 @@ "The Markdown in docstrings is processed with the [3BMD][3bmd] library." (@markdown-indentation section) + (@markdown-images section) (@markdown-syntax-highlighting section) (@mathjax section)) @@ -46,6 +47,29 @@ leading spaces that is common to all non-blank lines." """) + +(defsection @markdown-images (:title "Images") + """ + You can use markdown syntax for inserting images: + + ``` + ![](images/demo.gif) + ``` + + This code will search image file in the current ASDF system directory. + + But some times you may want to refer images from some other ASDF system. + This could be useful for dist storage optimization - if you main system changes frequently + but images are not, then it is better to keep images in a separate ASDF system and repository. + + In this case you can give asdf system as a prefix to the image path: + + ``` + ![](asdf:some-system:images/demo.gif) + ``` + + """) + (defsection @markdown-syntax-highlighting (:title "Syntax highlighting") "For syntax highlighting, github's [fenced code blocks][fenced-code-blocks] markdown extension to mark up code diff --git a/qlfile.lock b/qlfile.lock index aab4797..db1791f 100644 --- a/qlfile.lock +++ b/qlfile.lock @@ -1,8 +1,8 @@ ("quicklisp" . (:class qlot/source/dist:source-dist - :initargs (:distribution "https://beta.quicklisp.org/dist/quicklisp.txt" :%version :latest) - :version "2023-10-21")) + :initargs (:distribution "http://beta.quicklisp.org/dist/quicklisp.txt" :%version :latest) + :version "2024-10-12")) ("ultralisp" . (:class qlot/source/dist:source-dist - :initargs (:distribution "https://dist.ultralisp.org" :%version :latest) - :version "20240829155500")) + :initargs (:distribution "http://dist.ultralisp.org" :%version :latest) + :version "20241210203500")) diff --git a/src/autodoc.lisp b/src/autodoc.lisp index b9c978c..156fc9e 100644 --- a/src/autodoc.lisp +++ b/src/autodoc.lisp @@ -172,12 +172,19 @@ ,@entries)))) -(defun make-entries (system &key (show-system-description-p nil)) +(defun make-entries (system &key + (show-system-description-p nil) + (ignore-packages nil)) (with-subsection-collector () (loop for package in (system-packages system) for package-name = (package-name package) - for section-name = (symbolicate "@" (string-upcase package-name) "?PACKAGE") - for package-section = (make-package-section section-name package) + for collect-this-package = (not (member package-name + ignore-packages + :test #'string-equal)) + for section-name = (when collect-this-package + (symbolicate "@" (string-upcase package-name) "?PACKAGE")) + for package-section = (when section-name + (make-package-section section-name package)) when package-section collect (list section-name 'section) into entries and @@ -190,13 +197,14 @@ (defmacro defautodoc (name (&key system - (title "API") - (show-system-description-p nil) - (readtable-symbol '*readtable*) - (section-class '40ants-doc:section) - (external-docs nil) - (external-links nil) - (ignore-words nil))) + (title "API") + (show-system-description-p nil) + (readtable-symbol '*readtable*) + (section-class '40ants-doc:section) + (external-docs nil) + (external-links nil) + (ignore-words nil) + (ignore-packages nil))) "Macro DEFAUTODOC collects all packages of the ASDF system and analyzes all external symbols. In resulting documentation symbols are grouped by packages and types. @@ -220,13 +228,20 @@ When SHOW-SYSTEM-DESCRIPTION-P argument is not NIL, section will be started from the description of the given ASDF system. + + Argument IGNORE-PACKAGES can be used to exclude some packages from autogenerated docs. + This feature was added to not generate docs for symbols created automaticall + by Telegram API spec in cl-telegram-bot, but might be useful for some other projects, + especially for ones which are using package-inferred ASDF system style. ```" (unless system (error ":SYSTEM argument is required for DEFAUTODOC macro.")) (multiple-value-bind (subsections entries) - (make-entries system :show-system-description-p show-system-description-p) + (make-entries system + :show-system-description-p show-system-description-p + :ignore-packages ignore-packages) `(progn (defsection ,name (:title ,title :readtable-symbol ,readtable-symbol diff --git a/src/changelog.lisp b/src/changelog.lisp index 8dad500..debba0e 100644 --- a/src/changelog.lisp +++ b/src/changelog.lisp @@ -153,6 +153,12 @@ "CLEAN-URLS" ;; These objects are not documented yet: "40ANTS-DOC/COMMONDOC/XREF:XREF")) + (0.19.0 2024-12-13 + "* Argument IGNORE-PACKAGES was added to 40ANTS-DOC/AUTODOC:DEFAUTODOC macro. + It can be used to exclude some packages from autogenerated docs. + * Image URLs now can be specified relative to some other ASDF system. + For example `![](asdf:some-other-system:images/demo.gif) will look for the image + inside the directory of `some-other-system` ASDF system.") (0.18.0 2024-08-29 "* Now default theme looks good on mobile devices.") (0.17.4 2024-05-15