Skip to content

Commit

Permalink
IGNORE-PACKAGES argument was added to DEFSECTION macro.
Browse files Browse the repository at this point in the history 
Packages listed in this argument allows to muffle this warning:

```
Object referenced as #<XREF FOO:BAR CLASS> in \"Some section\" is not documented.
```
  • Loading branch information
@svetlyak40wt
svetlyak40wt committed Jan 6, 2025
1 parent 66a4d43 commit 9124b04
Show file tree
Hide file tree
Showing 7 changed files with 282 additions and 163 deletions.
18 changes: 12 additions & 6 deletions full/commondoc/mapper.lisp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@
(:import-from #:40ants-doc-full/commondoc/bullet)
(:import-from #:40ants-doc/object-package
#:object-package)
(:import-from #:serapeum
#:soft-list-of
#:->)
(:export
#:map-nodes
#:node-supports-children
Expand Down Expand Up @@ -79,6 +82,9 @@
(funcall func))))


(-> current-path ()
(values (soft-list-of string) &optional))

(defun current-path ()
"Returns a list of section titles (strings)."
(unless (boundp '*path*)
Expand All @@ -87,13 +93,13 @@
(loop for item in (reverse *path*)
for title = (typecase item
(common-doc:section
(common-doc.ops:collect-all-text
(common-doc:title item)))
(common-doc.ops:collect-all-text
(common-doc:title item)))
(40ants-doc-full/commondoc/bullet::bullet
;; To always render a package specified version
;; of symbol names, we need to set keyword package here
(let ((*package* (find-package :keyword)))
(40ants-doc-full/commondoc/bullet::bullet-name item))))
;; To always render a package specified version
;; of symbol names, we need to set keyword package here
(let ((*package* (find-package :keyword)))
(40ants-doc-full/commondoc/bullet::bullet-name item))))
collect title))


Expand Down
277 changes: 158 additions & 119 deletions full/commondoc/page.lisp
View file

Large diffs are not rendered by default.

41 changes: 25 additions & 16 deletions full/commondoc/xref.lisp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@
(:import-from #:40ants-doc-full/commondoc/mapper
#:with-node-package)
(:import-from #:commondoc-markdown)
(:import-from #:40ants-doc/object-package)
(:import-from #:40ants-doc/object-package
#:object-package)
(:import-from #:40ants-doc-full/link)
(:export
#:make-xref
Expand Down Expand Up @@ -213,10 +214,18 @@
(defmethod 40ants-doc/object-package::object-package ((obj common-doc:document))
*package*)

(defmethod 40ants-doc/object-package::object-package ((obj common-doc:document-node))
(defmethod object-package ((obj common-doc:document-node))
*package*)


(defmethod object-package ((obj xref))
(cond
((xref-symbol obj)
(object-package (xref-symbol obj)))
(t
(call-next-method))))


(defun extract-symbols (node &aux inside-code-block inside-inline-code)
"Extracts non marked up symbols from COMMON-DOC:TEXT-NODE and replaces them with XREF objects."

Expand All @@ -240,22 +249,22 @@
(extractor (node)
(typecase node
(common-doc:text-node
(cond ((or inside-code-block
40ants-doc-full/commondoc/mapper::*inside-title*
40ants-doc-full/commondoc/mapper::*inside-link*)
node)
(inside-inline-code
;; If whole content of inline code is recognized
;; as a symbol, then we'll replace it with XREF:
(let ((result (extract-symbols-from-text node)))
(if (and (typep result 'xref)
(= (length (common-doc:text node))
(length (common-doc:text result))))
(cond ((or inside-code-block
40ants-doc-full/commondoc/mapper::*inside-title*
40ants-doc-full/commondoc/mapper::*inside-link*)
node)
(inside-inline-code
;; If whole content of inline code is recognized
;; as a symbol, then we'll replace it with XREF:
(let ((result (extract-symbols-from-text node)))
(if (and (typep result 'xref)
(= (length (common-doc:text node))
(length (common-doc:text result))))
result
node))
)
(t
(extract-symbols-from-text node))))
)
(t
(extract-symbols-from-text node))))
(t node))))
;; Here we we need to change *package*
;; to make sure, that all symbol mentions are parsed as if we being
Expand Down
27 changes: 27 additions & 0 deletions full/errors.lisp
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
(uiop:define-package #:40ants-doc-full/errors
(:use #:cl)
(:import-from #:serapeum
#:soft-list-of)
(:export #:40ants-doc-warning
#:object-is-not-documented
#:object-reference
#:breadcrumbs))
(in-package #:40ants-doc-full/errors)


(define-condition 40ants-doc-warning (warning)
())


(define-condition object-is-not-documented (40ants-doc-warning)
((reference :initarg :reference
:reader object-reference
:documentation "Object of class 40ANTS-DOC-FULL/COMMONDOC/XREF:XREF.")
(breadcrumbs :initarg :breadcrumbs
:type (soft-list-of string)
:reader breadcrumbs))
(:report (lambda (err stream)
(format stream
"Object referenced as ~A in ~{~A~^ / ~} is not documented."
(object-reference err)
(breadcrumbs err)))))
9 changes: 6 additions & 3 deletions src/autodoc.lisp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -239,9 +239,11 @@
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
This feature was added to not generate docs for symbols created automatically
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.
especially for ones which are using package-inferred ASDF system style. Warnings about
mentioning symbols from ignored packages are suppressed. Comparison of package names
is case-sensitive.
```"

(unless system
Expand All @@ -257,7 +259,8 @@
:section-class ,section-class
:external-docs ,external-docs
:external-links ,external-links
:ignore-words ,ignore-words)
:ignore-words ,ignore-words
:ignore-packages ,ignore-packages)
,@entries)

,@subsections)))
7 changes: 7 additions & 0 deletions src/changelog.lisp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,13 @@
"CLEAN-URLS"
;; These objects are not documented yet:
"40ANTS-DOC/COMMONDOC/XREF:XREF"))
(0.23.0 2025-01-06
"* IGNORE-PACKAGES argument was added to DEFSECTION macro. Packages
listed in this argument allows to muffle this warning:
```
Object referenced as #<XREF FOO:BAR CLASS> in \"Some section\" is not documented.
```")
(0.22.0 2025-01-05
"* Exported 40ANTS-DOC/OBJECT-PACKAGE:OBJECT-PACKAGE generic-function.
Define a method for it if you have created a new locative type
Expand Down
66 changes: 47 additions & 19 deletions src/core.lisp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@
(:import-from #:40ants-doc/object-package)
(:import-from #:40ants-doc/docstring
#:strip-docstring-indentation)
(:import-from #:serapeum
#:soft-list-of)
(:export #:defsection
#:exportable-locative-type-p
#:section
Expand All @@ -20,7 +22,8 @@
#:section-ignore-words
#:defsection-copy
#:section-external-docs
#:*symbols-with-ignored-missing-locations*))
#:*symbols-with-ignored-missing-locations*
#:section-ignore-packages))
(in-package #:40ants-doc)


Expand Down Expand Up @@ -59,18 +62,19 @@


(defmacro defsection (name (&key
(package '*package*)
;; TODO: Deprecate after 2023
(package-symbol nil)
(readtable-symbol '*readtable*)
(section-class 'section)
(export nil)
title
link-title-to
(discard-documentation-p *discard-documentation-p*)
(external-docs nil)
(external-links nil)
(ignore-words nil))
(package '*package*)
;; TODO: Deprecate after 2023
(package-symbol nil)
(readtable-symbol '*readtable*)
(section-class 'section)
(export nil)
title
link-title-to
(discard-documentation-p *discard-documentation-p*)
(external-docs nil)
(external-links nil)
(ignore-words nil)
(ignore-packages nil))
&body entries)
"Define a documentation section and maybe export referenced symbols.
A bit behind the scenes, a global variable with NAME is defined and
Expand Down Expand Up @@ -145,8 +149,13 @@
:IGNORE-WORDS allows to pass a list of strings which should not cause
warnings. Usually these are uppercased words which are not symbols
in the current package, like SLIME, LISP, etc."

in the current package, like SLIME, LISP, etc.
Argument IGNORE-PACKAGES can be used to ignore mentions of all symbols from these
packages. If given, it should be a list of strings. Comparison of
package names is case-sensitive.
"

;; Let's check the syntax as early as possible.
(setf entries
(transform-locative-symbols
Expand All @@ -170,6 +179,16 @@
(setf ignore-words
(list* 'list
ignore-words)))

(when (and (typep ignore-packages
'list)
(typep (first ignore-packages)
'string))
;; This allows to pass an unquoted list of words
;; to the macro, which is what you most commonly need.
(setf ignore-packages
(list* 'list
ignore-packages)))

(let ((export-form
(when export
Expand All @@ -186,11 +205,13 @@
:title ,title
:link-title-to (transform-link-title-to ',link-title-to)
:entries ,(if discard-documentation-p
()
`(transform-entries ',entries ',external-links))
()
`(transform-entries ',entries ',external-links))
:external-docs (list ,@(uiop:ensure-list external-docs))
:ignore-words (list
,@(eval ignore-words)))))))
,@(eval ignore-words))
:ignore-packages (list
,@(eval ignore-packages)))))))

(defclass section ()
((name
Expand Down Expand Up @@ -231,9 +252,16 @@
:documentation "A list of strings with URLs of other system's documentation.")
(ignore-words
:initarg :ignore-words
:type (soft-list-of string)
:initform nil
:reader section-ignore-words
:documentation "A list of strings to not warn about."))
:documentation "A list of strings to not warn about.")
(ignore-packages
:initarg :ignore-packages
:type (soft-list-of string)
:initform nil
:reader section-ignore-packages
:documentation "A list of strings denoting package names to not warn about."))
(:documentation "DEFSECTION stores its :NAME, :TITLE, :PACKAGE,
:READTABLE and :ENTRIES in [SECTION][class] objects."))

Expand Down

0 comments on commit 9124b04

Please sign in to comment.