Skip to content

Commit

Permalink
Merge pull request #55 from 40ants/exclude-packages-from-autodoc
Browse files Browse the repository at this point in the history
Argument IGNORE-PACKAGES was added to 40ANTS-DOC/AUTODOC:DEFAUTODOC macro
  • Loading branch information
svetlyak40wt authored Dec 13, 2024
2 parents e59784d + 4ae22ef commit f4aebe6
Show file tree
Hide file tree
Showing 5 changed files with 75 additions and 19 deletions.
19 changes: 15 additions & 4 deletions full/commondoc/image.lisp
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
24 changes: 24 additions & 0 deletions full/markdown.lisp
Original file line number Diff line number Diff line change
Expand Up @@ -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))

Expand Down Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions qlfile.lock
Original file line number Diff line number Diff line change
@@ -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"))
37 changes: 26 additions & 11 deletions src/autodoc.lisp
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand Down
6 changes: 6 additions & 0 deletions src/changelog.lisp
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit f4aebe6

Please sign in to comment.