From 1e0d586a6837953ef6689ec7c544d55df2eb7a3f Mon Sep 17 00:00:00 2001 From: Alexander Artemenko Date: Sun, 5 Dec 2021 00:13:36 +0300 Subject: [PATCH 1/6] Fixed the issue, when we tried to find uppercased xrefs inside inline code and links. --- src/changelog.lisp | 2 ++ src/commondoc/mapper.lisp | 13 +++++++++++++ src/commondoc/xref.lisp | 15 ++++++++++----- 3 files changed, 25 insertions(+), 5 deletions(-) diff --git a/src/changelog.lisp b/src/changelog.lisp index 69e14028..bfd104dc 100644 --- a/src/changelog.lisp +++ b/src/changelog.lisp @@ -143,6 +143,8 @@ "*DOCUMENT-DOWNCASE-UPPERCASE-CODE*" ;; These objects are not documented yet: "40ANTS-DOC/COMMONDOC/XREF:XREF")) + (0.6.0 2021-12-05 + "* Fixed the issue, when we tried to find uppercased xrefs inside inline code and links.") (0.5.8 2021-10-23 "* Fixed the way of how a TOC is built. Previosly it incorrectly shown nested COMMONDOC:SECTION objects.") (0.5.7 2021-10-21 diff --git a/src/commondoc/mapper.lisp b/src/commondoc/mapper.lisp index e58a9faa..9ac59408 100644 --- a/src/commondoc/mapper.lisp +++ b/src/commondoc/mapper.lisp @@ -22,6 +22,12 @@ This can be useful if we don't want to do something inside titles.") +(defvar *inside-link* nil + "Will be set to T when mapper goes down into a link + + This can be useful if we don't want to do something + inside web link.") + (defun do-nothing (node) (declare (ignore node)) @@ -171,6 +177,13 @@ (process-node-with-children node func :on-going-down on-going-down :on-going-up on-going-up)) + + (:method ((node common-doc:link) func &key + (on-going-down #'do-nothing) + (on-going-up #'do-nothing)) + (declare (ignore on-going-down on-going-up)) + (let ((*inside-link* t)) + (call-next-method))) (:method ((node common-doc:section) func &key (on-going-down #'do-nothing) (on-going-up #'do-nothing)) diff --git a/src/commondoc/xref.lisp b/src/commondoc/xref.lisp index 6bc78eb4..e8726618 100644 --- a/src/commondoc/xref.lisp +++ b/src/commondoc/xref.lisp @@ -206,18 +206,23 @@ ((go-down (node) ;; We need this flag because we want to turn off ;; symbol extraction inside code blocks - (when (typep node - 'common-doc:code-block) + (when (or (typep node + 'common-doc:code-block) + (typep node + 'common-doc:code)) (setf inside-code-block t))) (go-up (node) - (when (typep node - 'common-doc:code-block) + (when (or (typep node + 'common-doc:code-block) + (typep node + 'common-doc:code)) (setf inside-code-block nil))) (extractor (node) (typecase node (common-doc:text-node (if (or inside-code-block - 40ants-doc/commondoc/mapper::*inside-title*) + 40ants-doc/commondoc/mapper::*inside-title* + 40ants-doc/commondoc/mapper::*inside-link*) node (extract-symbols-from-text node))) (t node)))) From 93f3a0b018d0a7e0df21073d369148479e824237 Mon Sep 17 00:00:00 2001 From: Alexander Artemenko Date: Sun, 5 Dec 2021 15:34:33 +0300 Subject: [PATCH 2/6] Added EXTERNAL-LINKS argument to DEFSECTION macro. It can be useful, if you have a multiple text sections having the same external link. --- src/changelog.lisp | 4 ++- src/core.lisp | 69 +++++++++++++++++++++++++++++----------------- src/utils.lisp | 1 + 3 files changed, 47 insertions(+), 27 deletions(-) diff --git a/src/changelog.lisp b/src/changelog.lisp index bfd104dc..0b6c3e04 100644 --- a/src/changelog.lisp +++ b/src/changelog.lisp @@ -144,7 +144,9 @@ ;; These objects are not documented yet: "40ANTS-DOC/COMMONDOC/XREF:XREF")) (0.6.0 2021-12-05 - "* Fixed the issue, when we tried to find uppercased xrefs inside inline code and links.") + "* Fixed the issue, when we tried to find uppercased xrefs inside inline code and links. + * Added EXTERNAL-LINKS argument to DEFSECTION macro. It can be useful, if you have a multiple + text sections having the same external link.") (0.5.8 2021-10-23 "* Fixed the way of how a TOC is built. Previosly it incorrectly shown nested COMMONDOC:SECTION objects.") (0.5.7 2021-10-21 diff --git a/src/core.lisp b/src/core.lisp index 9f4e72d2..57f0fd0d 100644 --- a/src/core.lisp +++ b/src/core.lisp @@ -5,6 +5,8 @@ (:import-from #:40ants-doc/reference) (:import-from #:40ants-doc/locatives) (:import-from #:40ants-doc/object-package) + (:import-from #:40ants-doc/docstring + #:strip-docstring-indentation) (:export #:defsection #:exportable-locative-type-p #:section @@ -35,6 +37,7 @@ link-title-to (discard-documentation-p *discard-documentation-p*) (external-docs nil) + (external-links nil) (ignore-words nil)) &body entries) "Define a documentation section and maybe export referenced symbols. @@ -102,6 +105,12 @@ and you'll be able to mention symbols from them and have automatic cross-links. + EXTERNAL-LINKS argument could contain an alist of (\"name\" . \"URL\") pairs. + These pairs will be tranformed to [name]: URL text and appended to each + markdown part of the defined chapter. This argument is useful when you are + having more than one text part in the chapter and want to reference same + URL from all of them using short markdown links. + :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." @@ -111,7 +120,7 @@ (transform-locative-symbols entries)) - (transform-entries entries) + (transform-entries entries external-links) (transform-link-title-to link-title-to) (when (and (typep ignore-words @@ -140,7 +149,7 @@ :link-title-to (transform-link-title-to ',link-title-to) :entries ,(if discard-documentation-p () - `(transform-entries ',entries)) + `(transform-entries ',entries ',external-links)) :external-docs (list ,@(uiop:ensure-list external-docs)) :ignore-words (list ,@(eval ignore-words))))))) @@ -238,30 +247,38 @@ (ensure-list locative-2))) -(defun add-a-newline (text) - "Adds a new line text entries to make markdown parser correctly parse a header at the end of the text. - - Often you might end your text entry with a header like: - - ## API" - ;; and this function makes it work well - (concatenate 'string text " -")) - - -(defun transform-entries (entries) - (mapcar (lambda (entry) - (typecase entry - (string (add-a-newline entry)) - (symbol - (let ((value (symbol-value entry))) - (unless (typep value 'string) - (error "~S value should be a string." - entry)) - (add-a-newline value))) - (t - (entry-to-reference entry)))) - entries)) +(defun transform-entries (entries external-links) + (let ((external-links + (with-output-to-string (s) + (loop for (name . url) in external-links + do (format s "[~A]: ~A~&" + name + url))))) + (flet ((add-external-links (text) + "Adds markdown references to the end of the section piece. + + Beside that, it adds a new line text entries to make + markdown parser correctly parse a header at the + end of the text. + + Often you might end your text entry with a header like: + + ## API" + (format nil "~A~2&~A" + (strip-docstring-indentation text) + external-links))) + (mapcar (lambda (entry) + (typecase entry + (string (add-external-links entry)) + (symbol + (let ((value (symbol-value entry))) + (unless (typep value 'string) + (error "~S value should be a string." + entry)) + (add-external-links value))) + (t + (entry-to-reference entry)))) + entries)))) (defun entry-to-reference (entry) (destructuring-bind (symbol locative &key export) entry diff --git a/src/utils.lisp b/src/utils.lisp index d28196d1..f3a88970 100644 --- a/src/utils.lisp +++ b/src/utils.lisp @@ -204,6 +204,7 @@ (defun trim-whitespace (string) (string-trim #.(format nil "~{~A~}" *whitespace-chars*) string)) +;; TODO: probably replace it with strip-docstring-indentation? (defun strip-longest-common-prefix (string chars &key (first-line-special-p t)) (let ((prefix (longest-common-prefix string chars :first-line-special-p first-line-special-p))) From d67e3e86acc7c8e464dfd843518da5fd46359430 Mon Sep 17 00:00:00 2001 From: Alexander Artemenko Date: Sun, 5 Dec 2021 15:38:06 +0300 Subject: [PATCH 3/6] Now it is possible to use 40ANTS-DOC/IGNORED-WORDS:IGNORE-WORDS-IN-PACKAGE to suppress warning on symbols which are exported but not documented. --- src/changelog.lisp | 4 ++- src/commondoc/page.lisp | 4 ++- src/ignored-words.lisp | 9 ++++++- src/locatives/definers.lisp | 51 ++++++++++++++++++++----------------- 4 files changed, 42 insertions(+), 26 deletions(-) diff --git a/src/changelog.lisp b/src/changelog.lisp index 0b6c3e04..aa7f8f4d 100644 --- a/src/changelog.lisp +++ b/src/changelog.lisp @@ -146,7 +146,9 @@ (0.6.0 2021-12-05 "* Fixed the issue, when we tried to find uppercased xrefs inside inline code and links. * Added EXTERNAL-LINKS argument to DEFSECTION macro. It can be useful, if you have a multiple - text sections having the same external link.") + text sections having the same external link. + * Now it is possible to use 40ANTS-DOC/IGNORED-WORDS:IGNORE-WORDS-IN-PACKAGE + to suppress warning on symbols which are exported but not documented.") (0.5.8 2021-10-23 "* Fixed the way of how a TOC is built. Previosly it incorrectly shown nested COMMONDOC:SECTION objects.") (0.5.7 2021-10-21 diff --git a/src/commondoc/page.lisp b/src/commondoc/page.lisp index 802ed409..087ae1b8 100644 --- a/src/commondoc/page.lisp +++ b/src/commondoc/page.lisp @@ -173,10 +173,12 @@ var DOCUMENTATION_OPTIONS = { ;; exported, because these can be some inner chapters. (not (typep node '40ants-doc/commondoc/section:documentation-section))) (let* ((reference (40ants-doc/commondoc/piece::doc-reference node)) + (package (40ants-doc/object-package::object-package node)) (obj (40ants-doc/reference::reference-object reference))) (typecase obj (symbol - (unless (is-external obj) + (when (and (not (is-external obj)) + (not (ignored-in-package obj package))) (warn "Symbol ~S is documented but not exported from it's package." obj)))))) node)) diff --git a/src/ignored-words.lisp b/src/ignored-words.lisp index d54d3b47..2e41b528 100644 --- a/src/ignored-words.lisp +++ b/src/ignored-words.lisp @@ -25,9 +25,16 @@ (defmacro ignore-words-in-package (&rest symbols-or-strings) + "Adds given symbols or string to ignore list bound to the current package. + + You will not be warned when one of these symbols is not documented + or documented and not exported from the package." `(eval-when (:compile-toplevel :load-toplevel :execute) (setf (gethash *package* *package-ignore-words*) - (list ,@symbols-or-strings)))) + (union + (gethash *package* *package-ignore-words*) + (list ,@symbols-or-strings) + :test 'equal)))) (defun ignored-in-package (symbol-or-string package) diff --git a/src/locatives/definers.lisp b/src/locatives/definers.lisp index 23b8bc8d..cf910287 100644 --- a/src/locatives/definers.lisp +++ b/src/locatives/definers.lisp @@ -49,27 +49,32 @@ After all this, `(UP DIRECTION)` refers to the `DEFINE-DIRECTION` form above.""" (check-body-docstring docstring) - `(progn - (40ants-doc/locatives/base::define-locative-type ,locative-type ,lambda-list ,@docstring) - (defmethod 40ants-doc/locatives/base::locate-object (symbol (locative-type (eql ',locative-type)) locative-args) - (or (40ants-doc/locatives/base::symbol-lambda-list-method symbol ',locative-type) - (40ants-doc/locatives/base::locate-error)) - (40ants-doc/reference::make-reference symbol (cons locative-type locative-args))) - - - (defmethod 40ants-doc/commondoc/builder::reference-to-commondoc ((symbol symbol) (locative-type (eql ',locative-type)) locative-args) - (let* ((method (40ants-doc/locatives/base::symbol-lambda-list-method symbol ',locative-type)) - (arglist (40ants-doc/locatives/base::symbol-lambda-list symbol ',locative-type)) - (reference (40ants-doc/reference::make-reference - symbol (cons locative-type locative-args))) - (docstring (40ants-doc/docstring:get-docstring method t)) - (children (when docstring - (40ants-doc/commondoc/markdown:parse-markdown docstring)))) + ;; We need to create a symbol with the name of locative-type inside 40ANTS-DOC/LOCATIVES, + ;; because when we refer this locative from the documentation section, the symbol denoting + ;; a locative will be searched in that package + (let ((locative-type (intern (symbol-name locative-type) + (find-package "40ANTS-DOC/LOCATIVES")))) + `(progn + (40ants-doc/locatives/base::define-locative-type ,locative-type ,lambda-list ,@docstring) + (defmethod 40ants-doc/locatives/base::locate-object (symbol (locative-type (eql ',locative-type)) locative-args) + (or (40ants-doc/locatives/base::symbol-lambda-list-method symbol ',locative-type) + (40ants-doc/locatives/base::locate-error)) + (40ants-doc/reference::make-reference symbol (cons locative-type locative-args))) + + + (defmethod 40ants-doc/commondoc/builder::reference-to-commondoc ((symbol symbol) (locative-type (eql ',locative-type)) locative-args) + (let* ((method (40ants-doc/locatives/base::symbol-lambda-list-method symbol ',locative-type)) + (arglist (40ants-doc/locatives/base::symbol-lambda-list symbol ',locative-type)) + (reference (40ants-doc/reference::make-reference + symbol (cons locative-type locative-args))) + (docstring (40ants-doc/docstring:get-docstring method t)) + (children (when docstring + (40ants-doc/commondoc/markdown:parse-markdown docstring)))) - (40ants-doc/commondoc/bullet:make-bullet reference - :arglist arglist - :children children - :ignore-words symbol))) - - (defmethod 40ants-doc/locatives/base:locate-and-find-source (symbol (locative-type (eql ',locative-type)) locative-args) - (40ants-doc/source-api:find-source (40ants-doc/locatives/base::symbol-lambda-list-method symbol ',locative-type))))) + (40ants-doc/commondoc/bullet:make-bullet reference + :arglist arglist + :children children + :ignore-words symbol))) + + (defmethod 40ants-doc/locatives/base:locate-and-find-source (symbol (locative-type (eql ',locative-type)) locative-args) + (40ants-doc/source-api:find-source (40ants-doc/locatives/base::symbol-lambda-list-method symbol ',locative-type)))))) From 26d259fe3c44285e327d24b181ad87f2e9910b68 Mon Sep 17 00:00:00 2001 From: Alexander Artemenko Date: Sun, 5 Dec 2021 16:32:30 +0300 Subject: [PATCH 4/6] Documented ignored-words package. --- ChangeLog.md | 65 +++++++++++++++++------------ README.md | 92 ++++++++++++++++++++---------------------- src/doc.lisp | 7 +++- src/ignored-words.lisp | 6 ++- 4 files changed, 93 insertions(+), 77 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index 50b1ed5e..d07a70ac 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -2,6 +2,18 @@ # ChangeLog + + +## 0.6.0 (2021-12-05) + +* Fixed the issue, when we tried to find uppercased xrefs inside inline code and links. + +* Added `EXTERNAL-LINKS` argument to [`defsection`][3e7c] macro. It can be useful, if you have a multiple + text sections having the same external link. + +* Now it is possible to use [`40ants-doc/ignored-words:ignore-words-in-package`][0cce] + to suppress warning on symbols which are exported but not documented. + ## 0.5.8 (2021-10-23) @@ -12,7 +24,7 @@ ## 0.5.7 (2021-10-21) -* [`defsection`][4e8b] macro now supports `EXTERNAL-DOCS` argument. +* [`defsection`][3e7c] macro now supports `EXTERNAL-DOCS` argument. @@ -40,7 +52,7 @@ Object referenced as # in ChangeLog / 0.5.3 ## 0.5.4 (2021-09-11) -* Included changelog.lisp into the [`40ants-doc`][a2c7] system. +* Included changelog.lisp into the [`40ants-doc`][bdb2] system. @@ -67,7 +79,7 @@ Object referenced as # in ChangeLog / 0.5.3 ## 0.5.0 (2021-09-06) -* Now [`40ants-doc:defsection`][4e8b] macro accepts `EXTERNAL-DOCS` argument. +* Now [`40ants-doc:defsection`][3e7c] macro accepts `EXTERNAL-DOCS` argument. Together with `HTML` pages, `references.json` file is rendered, and you can provide a list of urls of external libraries' documentation to have an automatic cross-referencing between them. @@ -76,10 +88,10 @@ cross-referencing between them. ## 0.4.1 (2021-09-05) -* Function [`40ants-doc/builder:get-current-asdf-system`][15d3] was added. Now you can use it to do something interesting +* Function [`40ants-doc/builder:get-current-asdf-system`][bf98] was added. Now you can use it to do something interesting like showing "Fork me on the GitHub" stripe [as my own theme do][2fa5]. -* Markdown files now will have a footer saying that a file was generated by [`40ants-doc`][a2c7]. +* Markdown files now will have a footer saying that a file was generated by [`40ants-doc`][bdb2]. * An `RSS` feed is generated for changelog. Also, changelog items can have a date now. @@ -88,7 +100,7 @@ cross-referencing between them. ## 0.4.0 (2021-09-05) * `*DOCUMENT-NORMALIZE-PACKAGES*` variable was replaced with `FULL-PACKAGE-NAMES` argument -of [`40ants-doc/builder:render-to-files`][05c0] function. +of [`40ants-doc/builder:render-to-files`][084c] function. @@ -99,7 +111,7 @@ of [`40ants-doc/builder:render-to-files`][05c0] function. * Added a protocol to define new color themes and change page layout. Three new themes are available out of the box. - Read more at [`Defining a Custom Theme`][bcaa] section. + Read more at [`Defining a Custom Theme`][22a0] section. @@ -116,7 +128,7 @@ of [`40ants-doc/builder:render-to-files`][05c0] function. * Now defsection does not export nor mentioned symbols nor the name of the section It is better to have explicit exports. -* [`40ants-doc/locatives:include`][359f] locative now does not support `:HEADER`, `:FOOTER` and some other arguments. Use `:LANG` argument instead. +* [`40ants-doc/locatives:include`][e263] locative now does not support `:HEADER`, `:FOOTER` and some other arguments. Use `:LANG` argument instead. * Added code highlighting using Highlight.js library. @@ -126,12 +138,12 @@ of [`40ants-doc/builder:render-to-files`][05c0] function. * Elisp code for transcriptions was fixed and now should word not only with `SLIME`, but also with `SLY`. -* [`40ants-doc:defsection`][4e8b] macro now does not generate export code +* [`40ants-doc:defsection`][3e7c] macro now does not generate export code if `:EXPORT` argument is `NIL`. * Functions `UPDATE-ASDF-SYSTEM-HTML-DOCS` and `UPDATE-ASDF-SYSTEM-README` - were replaced with [`40ants-doc/builder:update-asdf-system-docs`][0983], which also supports - ChangeLog.md generation. Use [`40ants-doc/changelog:defchangelog`][8c40] to define versions. + were replaced with [`40ants-doc/builder:update-asdf-system-docs`][f11d], which also supports + ChangeLog.md generation. Use [`40ants-doc/changelog:defchangelog`][28eb] to define versions. * Variables `*DOCUMENT-HTML-MAX-NAVIGATION-TABLE-OF-CONTENTS-LEVEL*` and `*DOCUMENT-MAX-TABLE-OF-CONTENTS-LEVEL*` were removed. Probably we'll return this @@ -140,7 +152,7 @@ of [`40ants-doc/builder:render-to-files`][05c0] function. * Removed `LOCATE-AND-DOCUMENT` generic function. * Links to the GitHub now are generated automatically, - if [`40ants-doc/builder:update-asdf-system-docs`][0983] function is used + if [`40ants-doc/builder:update-asdf-system-docs`][f11d] function is used and system definition has a `:SOURCE-CONTROL` slot. * Generic functions `COLLECT-REACHABLE-OBJECTS` and `LOCATE-AND-COLLECT-REACHABLE-OBJECTS` @@ -150,7 +162,7 @@ of [`40ants-doc/builder:render-to-files`][05c0] function. * Variable `*DOCUMENT-MIN-LINK-HASH-LENGTH*` was removed. Use `COMMONDOC-MARKDOWN:*MIN-LINK-HASH-LENGTH*` -* Functions [`40ants-doc/builder:update-asdf-system-docs`][0983] and [`40ants-doc/builder:render-to-files`][05c0] +* Functions [`40ants-doc/builder:update-asdf-system-docs`][f11d] and [`40ants-doc/builder:render-to-files`][084c] now accept `WARN-ON-UNDOCUMENTED-PACKAGES` argument and `CLEAN-URLS` argument. * Variable `*DOCUMENT-MARK-UP-SIGNATURES*` was removed. @@ -160,13 +172,13 @@ of [`40ants-doc/builder:render-to-files`][05c0] function. * Added warnings on symbols, referenced like internals, using `::`. -* Added [`40ants-doc:defsection-copy`][ad02] macro to define copy of the section but with a different name. +* Added [`40ants-doc:defsection-copy`][15ec] macro to define copy of the section but with a different name. ## 0.1.0 (2021-05-01) -* Project forked from [`MGL-PAX`][7927]. +* Project forked from [MGL-PAX][7927]. Code refactored into the package inferred system and core is separated to have minimum dependencies. @@ -176,7 +188,7 @@ of [`40ants-doc/builder:render-to-files`][05c0] function. file-subseq function was rewritten. * Locatives can be specified without a package prefix inside the defsection - because all locative symbols now live in [`40ants-doc/locatives`][d889] package. + because all locative symbols now live in [`40ants-doc/locatives`][dd8b] package. * Function update-asdf-system-readmes was renamed to update-asdf-system-readmes and now it generates only one `README` file. @@ -198,19 +210,20 @@ of [`40ants-doc/builder:render-to-files`][05c0] function. * Fixed docstring extraction for compiler macro. -[a2c7]: https://40ants.com/doc/#x-28-23A-28-2810-29-20BASE-CHAR-20-2E-20-2240ants-doc-22-29-20ASDF-2FSYSTEM-3ASYSTEM-29 -[d889]: https://40ants.com/doc/#x-28-23A-28-2820-29-20BASE-CHAR-20-2E-20-2240ANTS-DOC-2FLOCATIVES-22-29-20PACKAGE-29 -[15d3]: https://40ants.com/doc/#x-2840ANTS-DOC-2FBUILDER-3AGET-CURRENT-ASDF-SYSTEM-20FUNCTION-29 -[05c0]: https://40ants.com/doc/#x-2840ANTS-DOC-2FBUILDER-3ARENDER-TO-FILES-20FUNCTION-29 -[0983]: https://40ants.com/doc/#x-2840ANTS-DOC-2FBUILDER-3AUPDATE-ASDF-SYSTEM-DOCS-20FUNCTION-29 -[8c40]: https://40ants.com/doc/#x-2840ANTS-DOC-2FCHANGELOG-3ADEFCHANGELOG-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29 -[359f]: https://40ants.com/doc/#x-2840ANTS-DOC-2FLOCATIVES-3AINCLUDE-20-2840ANTS-DOC-2FLOCATIVES-3ALOCATIVE-29-29 -[bcaa]: https://40ants.com/doc/#x-2840ANTS-DOC-2FTHEMES-2FDOCS-3A-3A-40DEFINING-A-THEME-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 -[4e8b]: https://40ants.com/doc/#x-2840ANTS-DOC-3ADEFSECTION-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29 -[ad02]: https://40ants.com/doc/#x-2840ANTS-DOC-3ADEFSECTION-COPY-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29 [2fa5]: https://github.com/40ants/40ants-doc-theme-40ants/commit/917a4c1e72b0379f509bdee4864531e641c9ec4e#diff-47d16baea2d4ef710747f19c24df8cf7ef4f6bbbfd1dbb0ade55f47457b1e8feR155-R161 [7927]: https://github.com/melisgl/mgl-pax [140c]: https://www.sphinx-doc.org/ +[bdb2]: index.html#x-28-2240ants-doc-22-20ASDF-2FSYSTEM-3ASYSTEM-29 +[dd8b]: index.html#x-28-23A-28-2820-29-20BASE-CHAR-20-2E-20-2240ANTS-DOC-2FLOCATIVES-22-29-20PACKAGE-29 +[bf98]: index.html#x-2840ANTS-DOC-2FBUILDER-3AGET-CURRENT-ASDF-SYSTEM-20FUNCTION-29 +[084c]: index.html#x-2840ANTS-DOC-2FBUILDER-3ARENDER-TO-FILES-20FUNCTION-29 +[f11d]: index.html#x-2840ANTS-DOC-2FBUILDER-3AUPDATE-ASDF-SYSTEM-DOCS-20FUNCTION-29 +[28eb]: index.html#x-2840ANTS-DOC-2FCHANGELOG-3ADEFCHANGELOG-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29 +[0cce]: index.html#x-2840ANTS-DOC-2FIGNORED-WORDS-3AIGNORE-WORDS-IN-PACKAGE-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29 +[e263]: index.html#x-2840ANTS-DOC-2FLOCATIVES-3AINCLUDE-20-2840ANTS-DOC-2FLOCATIVES-3ALOCATIVE-29-29 +[22a0]: index.html#x-2840ANTS-DOC-2FTHEMES-2FDOCS-3A-3A-40DEFINING-A-THEME-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 +[3e7c]: index.html#x-2840ANTS-DOC-3ADEFSECTION-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29 +[15ec]: index.html#x-2840ANTS-DOC-3ADEFSECTION-COPY-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29 * * * ###### [generated by [40ANTS-DOC](https://40ants.com/doc/)] diff --git a/README.md b/README.md index ff524922..12b2f625 100644 --- a/README.md +++ b/README.md @@ -17,11 +17,11 @@ ## About this fork -This system is a fork of [`MGL-PAX`][7927]. +This system is a fork of [MGL-PAX][7927]. There are a few reasons, why I've created the fork. -The main goal is to extract a core features into the [`40ants-doc`][a2c7] system +The main goal is to extract a core features into the [`40ants-doc`][bdb2] system with as little dependencies as possible. This is important, because with `MGL-PAX`'s style, you define documentation sections in your library's code, which makes it dependent on the documentation system. However, heavy weight dependencies @@ -42,20 +42,20 @@ To introduce hooks for adding new markup languages, and `HTML` themes. Here are features already implemented in this fork: -* Core system [`40ants-doc`][a2c7] now has only two dependencies on `NAMED-READTABLES` +* Core system `40ANTS-DOC` now has only two dependencies on `NAMED-READTABLES` and `PYTHONIC-STRING-READER`. If you want to compile a documentation, load - [`40ants-doc-full`][a689] system which will download such dependencies as markdown + `40ANTS-DOC-FULL` system which will download such dependencies as markdown parser and more. * Now you don't have to import any locative symbols into your package. Import - only a [`defsection`][4e8b] macro and it will be enough to define documentation for + only a [`defsection`][3e7c] macro and it will be enough to define documentation for your library! * Added a warning mechanism, which will issue such warnings on words which looks like a symbol, but when real symbol or reference is absent: ` - WARNING: Unable to find target for reference # + WARNING: Unable to find target for reference # mentioned at 40Ants Doc Manual / Extension API / Reference Based Extensions ` @@ -66,13 +66,13 @@ Here are features already implemented in this fork: like GitHub pages. * It is possible to render pages in multiple formats and having cross references between them. - See [`Multiple Formats`][0b09]. + See [`Multiple Formats`][3a45]. -I'm planning to extend this fork even more. Read [`todo`][db30] section to learn about +I'm planning to extend this fork even more. Read [`todo`][2797] section to learn about proposed features or [start a new discussion][6f00] on the GitHub to suggest a new feature. -See full list of changes in the [`ChangeLog`][e991] section. +See full list of changes in the [`ChangeLog`][eafe] section. @@ -84,14 +84,14 @@ Read full documentation at [site 40ants.com/doc/][778d]. ## Tutorial -[`40ants-doc`][a2c7] provides an extremely poor man's Explorable Programming +[`40ants-doc`][bdb2] provides an extremely poor man's Explorable Programming environment. Narrative primarily lives in so called sections that mix markdown docstrings with references to functions, variables, etc, all of which should probably have their own docstrings. The primary focus is on making code easily explorable by using `SLIME`'s `M-.` (`slime-edit-definition`). See how to enable some -fanciness in [`Emacs Integration`][1201]. Generating documentation +fanciness in [`Emacs Integration`][03a4]. Generating documentation from sections and all the referenced items in Markdown or `HTML` format is also implemented. @@ -199,11 +199,11 @@ choose which. -## [class](5fe0) `foo-random:foo-random-state` () +## [class](422d) `foo-random:foo-random-state` () -## [reader](f58b) `foo-random:state` (foo-random-state) () +## [reader](c737) `foo-random:state` (foo-random-state) () Returns random foo's state. @@ -211,24 +211,24 @@ Hey we can also print states! -## [method](967c) `common-lisp:print-object` (object foo-random-state) stream +## [method](2829) `common-lisp:print-object` (object foo-random-state) stream -## [variable](8b8d) `foo-random:*foo-state*` # +## [variable](3f31) `foo-random:*foo-state*` # Much like `*RANDOM-STATE*` but uses the `FOO` algorithm. -## [function](cf1d) `foo-random:gaussian-random` stddev &key (random-state \*foo-state\*) +## [function](5d9d) `foo-random:gaussian-random` stddev &key (random-state \*foo-state\*) Return not a random number from a zero mean normal distribution with `STDDEV`. -## [function](08b1) `foo-random:uniform-random` limit &key (random-state \*foo-state\*) +## [function](22fc) `foo-random:uniform-random` limit &key (random-state \*foo-state\*) Return a random number from the between 0 and `LIMIT` (exclusive) uniform distribution. @@ -251,34 +251,34 @@ with `FOO`: ``` [2133]: #x-28FOO-RANDOM-3A-2AFOO-STATE-2A-20-28VARIABLE-29-29 -[5fe0]: https://github.com/40ants/doc/blob/327e38b6768b415be051c81120524bbe6908e3ec/tutorial.lisp#L34 -[f58b]: https://github.com/40ants/doc/blob/327e38b6768b415be051c81120524bbe6908e3ec/tutorial.lisp#L35 -[967c]: https://github.com/40ants/doc/blob/327e38b6768b415be051c81120524bbe6908e3ec/tutorial.lisp#L38 -[8b8d]: https://github.com/40ants/doc/blob/327e38b6768b415be051c81120524bbe6908e3ec/tutorial.lisp#L41 -[08b1]: https://github.com/40ants/doc/blob/327e38b6768b415be051c81120524bbe6908e3ec/tutorial.lisp#L44 -[cf1d]: https://github.com/40ants/doc/blob/327e38b6768b415be051c81120524bbe6908e3ec/tutorial.lisp#L50 +[422d]: https://github.com/40ants/doc/blob/2095395ae99b168ab58e04f16d96b6c870a95fd8/tutorial.lisp#L34 +[c737]: https://github.com/40ants/doc/blob/2095395ae99b168ab58e04f16d96b6c870a95fd8/tutorial.lisp#L35 +[2829]: https://github.com/40ants/doc/blob/2095395ae99b168ab58e04f16d96b6c870a95fd8/tutorial.lisp#L38 +[3f31]: https://github.com/40ants/doc/blob/2095395ae99b168ab58e04f16d96b6c870a95fd8/tutorial.lisp#L41 +[22fc]: https://github.com/40ants/doc/blob/2095395ae99b168ab58e04f16d96b6c870a95fd8/tutorial.lisp#L44 +[5d9d]: https://github.com/40ants/doc/blob/2095395ae99b168ab58e04f16d96b6c870a95fd8/tutorial.lisp#L50 ```` `MGL-PAX` supported the plain text format which was more readble when viewed from a simple text editor, but I've dropped support for plain text in this fork because most time documentation are read in the browser these days. -To render into the files, use [`40ants-doc/builder:render-to-files`][05c0] -and [`40ants-doc/builder:update-asdf-system-docs`][0983] functions. +To render into the files, use [`40ants-doc/builder:render-to-files`][084c] +and [`40ants-doc/builder:update-asdf-system-docs`][f11d] functions. Last one can even generate documentation for different, but related libraries at the same time with the output going to different files, but with cross-page links being automatically added for symbols -mentioned in docstrings. See [`Generating Documentation`][44e6] for +mentioned in docstrings. See `40ANTS-DOC/BUILDER::@GENERATING-DOCUMENTATION` for some convenience functions to cover the most common cases. -Note how `(*FOO-STATE* [variable][8f5a])` in the [`defsection`][4e8b] form includes its documentation in -`@FOO-RANDOM-MANUAL`. The symbols [`variable`][8f5a] and [`function`][0bdf] are just two -instances of 'locatives' which are used in [`defsection`][4e8b] to refer to -definitions tied to symbols. See [`Locative Types`][f187]. +Note how `(*FOO-STATE* VARIABLE)` in the [`defsection`][3e7c] form includes its documentation in +`@FOO-RANDOM-MANUAL`. The symbols [`variable`][d242] and [`function`][ccf9] are just two +instances of 'locatives' which are used in [`defsection`][3e7c] to refer to +definitions tied to symbols. See [`Locative Types`][5922]. The transcript in the code block tagged with `cl-transcript` is automatically checked for up-to-dateness. See -[`Transcripts`][c301]. +`40ANTS-DOC/TRANSCRIBE::@TRANSCRIPT`. @@ -299,30 +299,26 @@ automatically checked for up-to-dateness. See * Support custom `HTML` themes. * Generate `RSS` or Atom feed out of changelog items, defined with - [`40ants-doc/changelog:defchangelog`][8c40] macro. + [`40ants-doc/changelog:defchangelog`][28eb] macro. * Make some warnings compile-time for defsection and show them in the Emacs, if possible. +[eafe]: changelog.html#x-2840ANTS-DOC-2FCHANGELOG-3A-40CHANGELOG-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 [778d]: https://40ants.com/doc/ -[a2c7]: https://40ants.com/doc/#x-28-23A-28-2810-29-20BASE-CHAR-20-2E-20-2240ants-doc-22-29-20ASDF-2FSYSTEM-3ASYSTEM-29 -[a689]: https://40ants.com/doc/#x-28-23A-28-2815-29-20BASE-CHAR-20-2E-20-2240ants-doc-full-22-29-20ASDF-2FSYSTEM-3ASYSTEM-29 -[44e6]: https://40ants.com/doc/#x-2840ANTS-DOC-2FBUILDER-3A-3A-40GENERATING-DOCUMENTATION-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 -[0b09]: https://40ants.com/doc/#x-2840ANTS-DOC-2FBUILDER-3A-3A-40RENDERING-MULTIPLE-FORMATS-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 -[05c0]: https://40ants.com/doc/#x-2840ANTS-DOC-2FBUILDER-3ARENDER-TO-FILES-20FUNCTION-29 -[0983]: https://40ants.com/doc/#x-2840ANTS-DOC-2FBUILDER-3AUPDATE-ASDF-SYSTEM-DOCS-20FUNCTION-29 -[8c40]: https://40ants.com/doc/#x-2840ANTS-DOC-2FCHANGELOG-3ADEFCHANGELOG-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29 -[1201]: https://40ants.com/doc/#x-2840ANTS-DOC-2FDOC-3A-3A-40EMACS-INTEGRATION-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 -[f187]: https://40ants.com/doc/#x-2840ANTS-DOC-2FDOC-3A-3A-40LOCATIVE-TYPES-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 -[db30]: https://40ants.com/doc/#x-2840ANTS-DOC-2FDOC-3A-3A-40TODO-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 -[c301]: https://40ants.com/doc/#x-2840ANTS-DOC-2FTRANSCRIBE-3A-3A-40TRANSCRIPT-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 -[4e8b]: https://40ants.com/doc/#x-2840ANTS-DOC-3ADEFSECTION-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29 -[0bdf]: https://40ants.com/doc/#x-28FUNCTION-20-2840ANTS-DOC-2FLOCATIVES-3ALOCATIVE-29-29 -[c0cd]: https://40ants.com/doc/#x-28GENERIC-FUNCTION-20-2840ANTS-DOC-2FLOCATIVES-3ALOCATIVE-29-29 -[8f5a]: https://40ants.com/doc/#x-28VARIABLE-20-2840ANTS-DOC-2FLOCATIVES-3ALOCATIVE-29-29 -[e991]: https://40ants.com/doc/changelog/#x-2840ANTS-DOC-2FCHANGELOG-3A-40CHANGELOG-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 [6f00]: https://github.com/40ants/doc/discussions [7927]: https://github.com/melisgl/mgl-pax +[bdb2]: index.html#x-28-2240ants-doc-22-20ASDF-2FSYSTEM-3ASYSTEM-29 +[3a45]: index.html#x-2840ANTS-DOC-2FBUILDER-3A-3A-40RENDERING-MULTIPLE-FORMATS-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 +[084c]: index.html#x-2840ANTS-DOC-2FBUILDER-3ARENDER-TO-FILES-20FUNCTION-29 +[f11d]: index.html#x-2840ANTS-DOC-2FBUILDER-3AUPDATE-ASDF-SYSTEM-DOCS-20FUNCTION-29 +[28eb]: index.html#x-2840ANTS-DOC-2FCHANGELOG-3ADEFCHANGELOG-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29 +[03a4]: index.html#x-2840ANTS-DOC-2FDOC-3A-3A-40EMACS-INTEGRATION-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 +[5922]: index.html#x-2840ANTS-DOC-2FDOC-3A-3A-40LOCATIVE-TYPES-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 +[2797]: index.html#x-2840ANTS-DOC-2FDOC-3A-3A-40TODO-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 +[3e7c]: index.html#x-2840ANTS-DOC-3ADEFSECTION-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29 +[ccf9]: index.html#x-28FUNCTION-20-2840ANTS-DOC-2FLOCATIVES-3ALOCATIVE-29-29 +[d242]: index.html#x-28VARIABLE-20-2840ANTS-DOC-2FLOCATIVES-3ALOCATIVE-29-29 * * * ###### [generated by [40ANTS-DOC](https://40ants.com/doc/)] diff --git a/src/doc.lisp b/src/doc.lisp index 410c1095..677c86af 100644 --- a/src/doc.lisp +++ b/src/doc.lisp @@ -24,6 +24,7 @@ (:import-from #:40ants-doc/themes/docs) (:import-from #:docs-config #:docs-config) + (:import-from #:40ants-doc/ignored-words) (:export #:@index #:@readme)) @@ -426,7 +427,10 @@ See full list of changes in the 40ANTS-DOC/CHANGELOG::@CHANGELOG section. (defsection @defining-sections (:title "Defining Sections") (40ants-doc:defsection macro) (40ants-doc:defsection-copy macro) - (40ants-doc:*discard-documentation-p* variable)) + (40ants-doc:*discard-documentation-p* variable) + (40ants-doc/ignored-words:ignored-words generic-function) + (40ants-doc/ignored-words:supports-ignored-words-p generic-function) + (40ants-doc/ignored-words:ignore-words-in-package macro)) (defsection @cross-referencing (:title "Cross-referencing") @@ -531,6 +535,7 @@ See full list of changes in the 40ANTS-DOC/CHANGELOG::@CHANGELOG section. (constant locative) (macro locative) (compiler-macro locative) + (symbol-macro locative) (function locative) (generic-function locative) (method locative) diff --git a/src/ignored-words.lisp b/src/ignored-words.lisp index 2e41b528..d3e82a60 100644 --- a/src/ignored-words.lisp +++ b/src/ignored-words.lisp @@ -3,8 +3,7 @@ (:export #:ignored-words #:supports-ignored-words-p - #:ignore-words-in-package - #:ignored-in-package)) + #:ignore-words-in-package)) (in-package 40ants-doc/ignored-words) @@ -13,6 +12,7 @@ (defgeneric supports-ignored-words-p (obj) + (:documentation "Should return `T` if objects implements a method for IGNORED-WORDS generic-function.") (:method ((obj t)) nil) (:method ((obj package)) @@ -20,6 +20,7 @@ (defgeneric ignored-words (obj) + (:documentation "Returns a list of words or symbols to ignore in OBJ's documentation.") (:method ((obj package)) (gethash obj *package-ignore-words*))) @@ -38,6 +39,7 @@ (defun ignored-in-package (symbol-or-string package) + "Checks if given symbol or string is ignored in a package." (member symbol-or-string (gethash package *package-ignore-words*) :test #'equal)) From 8fcdfabaf4f7e06de256d6a4813ca4a97c617db4 Mon Sep 17 00:00:00 2001 From: Alexander Artemenko Date: Sun, 5 Dec 2021 18:44:51 +0300 Subject: [PATCH 5/6] Fixed tests. --- README.md | 24 ++++++++++---------- src/commondoc/utils.lisp | 3 ++- src/commondoc/xref.lisp | 48 ++++++++++++++++++++++++++-------------- src/docstring.lisp | 20 ++++++++++++++--- src/swank.lisp | 6 +++-- src/transcribe.lisp | 3 ++- src/utils.lisp | 16 +++----------- 7 files changed, 72 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 12b2f625..f73871e5 100644 --- a/README.md +++ b/README.md @@ -199,11 +199,11 @@ choose which. -## [class](422d) `foo-random:foo-random-state` () +## [class](2898) `foo-random:foo-random-state` () -## [reader](c737) `foo-random:state` (foo-random-state) () +## [reader](b444) `foo-random:state` (foo-random-state) () Returns random foo's state. @@ -211,24 +211,24 @@ Hey we can also print states! -## [method](2829) `common-lisp:print-object` (object foo-random-state) stream +## [method](6412) `common-lisp:print-object` (object foo-random-state) stream -## [variable](3f31) `foo-random:*foo-state*` # +## [variable](9bdc) `foo-random:*foo-state*` # Much like `*RANDOM-STATE*` but uses the `FOO` algorithm. -## [function](5d9d) `foo-random:gaussian-random` stddev &key (random-state \*foo-state\*) +## [function](a169) `foo-random:gaussian-random` stddev &key (random-state \*foo-state\*) Return not a random number from a zero mean normal distribution with `STDDEV`. -## [function](22fc) `foo-random:uniform-random` limit &key (random-state \*foo-state\*) +## [function](e414) `foo-random:uniform-random` limit &key (random-state \*foo-state\*) Return a random number from the between 0 and `LIMIT` (exclusive) uniform distribution. @@ -251,12 +251,12 @@ with `FOO`: ``` [2133]: #x-28FOO-RANDOM-3A-2AFOO-STATE-2A-20-28VARIABLE-29-29 -[422d]: https://github.com/40ants/doc/blob/2095395ae99b168ab58e04f16d96b6c870a95fd8/tutorial.lisp#L34 -[c737]: https://github.com/40ants/doc/blob/2095395ae99b168ab58e04f16d96b6c870a95fd8/tutorial.lisp#L35 -[2829]: https://github.com/40ants/doc/blob/2095395ae99b168ab58e04f16d96b6c870a95fd8/tutorial.lisp#L38 -[3f31]: https://github.com/40ants/doc/blob/2095395ae99b168ab58e04f16d96b6c870a95fd8/tutorial.lisp#L41 -[22fc]: https://github.com/40ants/doc/blob/2095395ae99b168ab58e04f16d96b6c870a95fd8/tutorial.lisp#L44 -[5d9d]: https://github.com/40ants/doc/blob/2095395ae99b168ab58e04f16d96b6c870a95fd8/tutorial.lisp#L50 +[2898]: https://github.com/40ants/doc/blob/26d259fe3c44285e327d24b181ad87f2e9910b68/tutorial.lisp#L34 +[b444]: https://github.com/40ants/doc/blob/26d259fe3c44285e327d24b181ad87f2e9910b68/tutorial.lisp#L35 +[6412]: https://github.com/40ants/doc/blob/26d259fe3c44285e327d24b181ad87f2e9910b68/tutorial.lisp#L38 +[9bdc]: https://github.com/40ants/doc/blob/26d259fe3c44285e327d24b181ad87f2e9910b68/tutorial.lisp#L41 +[e414]: https://github.com/40ants/doc/blob/26d259fe3c44285e327d24b181ad87f2e9910b68/tutorial.lisp#L44 +[a169]: https://github.com/40ants/doc/blob/26d259fe3c44285e327d24b181ad87f2e9910b68/tutorial.lisp#L50 ```` `MGL-PAX` supported the plain text format which was more readble when viewed from a simple text editor, but I've dropped support for plain text in this fork diff --git a/src/commondoc/utils.lisp b/src/commondoc/utils.lisp index 03284c76..0696c780 100644 --- a/src/commondoc/utils.lisp +++ b/src/commondoc/utils.lisp @@ -2,7 +2,8 @@ (:use #:cl) (:import-from #:40ants-doc/swank) (:import-from #:40ants-doc/utils - #:maybe-downcase + #:maybe-downcase) + (:import-from #:40ants-doc/docstring #:*whitespace-chars*) (:import-from #:str) (:import-from #:40ants-doc/commondoc/mapper diff --git a/src/commondoc/xref.lisp b/src/commondoc/xref.lisp index e8726618..97f12d5b 100644 --- a/src/commondoc/xref.lisp +++ b/src/commondoc/xref.lisp @@ -77,6 +77,10 @@ :locative locative)) +(defmethod common-doc:text ((xref xref)) + (xref-name xref)) + + (defmethod print-object ((xref xref) stream) (print-unreadable-object (xref stream :type t) (format stream "~S~:[~; ~A~]" @@ -199,32 +203,44 @@ *package*) -(defun extract-symbols (node &aux inside-code-block) +(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." (labels ((go-down (node) ;; We need this flag because we want to turn off ;; symbol extraction inside code blocks - (when (or (typep node - 'common-doc:code-block) - (typep node - 'common-doc:code)) - (setf inside-code-block t))) + (when (typep node + 'common-doc:code-block) + (setf inside-code-block t)) + (when (typep node + 'common-doc:code) + (setf inside-inline-code t))) (go-up (node) - (when (or (typep node - 'common-doc:code-block) - (typep node - 'common-doc:code)) - (setf inside-code-block nil))) + (when (typep node + 'common-doc:code-block) + (setf inside-code-block nil)) + (when (typep node + 'common-doc:code) + (setf inside-inline-code nil))) (extractor (node) (typecase node (common-doc:text-node - (if (or inside-code-block - 40ants-doc/commondoc/mapper::*inside-title* - 40ants-doc/commondoc/mapper::*inside-link*) - node - (extract-symbols-from-text node))) + (cond ((or inside-code-block + 40ants-doc/commondoc/mapper::*inside-title* + 40ants-doc/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 (= (length (common-doc:text node)) + (length (common-doc:text result))) + result + 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 diff --git a/src/docstring.lisp b/src/docstring.lisp index 7a8560d1..60601bc7 100644 --- a/src/docstring.lisp +++ b/src/docstring.lisp @@ -1,11 +1,13 @@ (defpackage #:40ants-doc/docstring (:use #:cl) - (:import-from #:40ants-doc/utils) (:export #:strip-docstring-indentation #:get-docstring)) (in-package 40ants-doc/docstring) +(eval-when (:compile-toplevel :load-toplevel :execute) + (defparameter *whitespace-chars* + '(#\Space #\Tab #\Return #\Newline #\Linefeed #\Page))) (defun n-leading-spaces (line) (let ((n 0)) @@ -14,6 +16,16 @@ do (incf n)) n)) +(defun whitespacep (char) + (member char *whitespace-chars*)) + +(defun blankp (string) + (every #'whitespacep string)) + +(defun trim-whitespace (string) + (string-trim #.(format nil "~{~A~}" *whitespace-chars*) string)) + + ;;; Return the minimum number of leading spaces in non-blank lines ;;; after the first. (defun docstring-indentation (docstring &key (first-line-special-p t)) @@ -23,7 +35,7 @@ for line = (read-line s nil nil) while line do (when (and (or (not first-line-special-p) (plusp i)) - (not (40ants-doc/utils::blankp line))) + (not (blankp line))) (when (or (null n-min-indentation) (< (n-leading-spaces line) n-min-indentation)) (setq n-min-indentation (n-leading-spaces line)))))) @@ -44,7 +56,9 @@ (return)) (if (and first-line-special-p (zerop i)) (write-string line out) - (write-string (40ants-doc/utils::subseq* line indentation) out)) + (write-string (subseq line (min (length line) + indentation)) + out)) (unless missing-newline-p (terpri out)))))) indentation))) diff --git a/src/swank.lisp b/src/swank.lisp index 56ed42a5..8ab18498 100644 --- a/src/swank.lisp +++ b/src/swank.lisp @@ -6,6 +6,8 @@ (:import-from #:pythonic-string-reader) (:import-from #:40ants-doc/utils) (:import-from #:40ants-doc/source-api) + (:import-from #:40ants-doc/docstring + #:trim-whitespace) (:export #:locate-definition-for-emacs)) (in-package 40ants-doc/swank) @@ -27,7 +29,7 @@ ;;; string arguments and returns a location suitable for ;;; make-slime-xref. (defun locate-definition-for-emacs (name locative-string) - (let ((locative-string (40ants-doc/utils::trim-whitespace locative-string))) + (let ((locative-string (trim-whitespace locative-string))) (swank-backend::converting-errors-to-error-location (swank::with-buffer-syntax () (or @@ -91,7 +93,7 @@ (swank::find-definitions-find-symbol-or-package string)) (if found symbol - (let ((first-char-pos (position-if-not #'40ants-doc/utils::whitespacep string))) + (let ((first-char-pos (position-if-not #'40ants-doc/docstring::whitespacep string))) (when (and first-char-pos (char= #\()) ;; Looks like a list. The first element must be an diff --git a/src/transcribe.lisp b/src/transcribe.lisp index 5dd628f3..d283bd27 100644 --- a/src/transcribe.lisp +++ b/src/transcribe.lisp @@ -20,7 +20,8 @@ (:import-from #:40ants-doc/utils #:write-prefixed-lines #:read-prefixed-lines - #:read-line* + #:read-line*) + (:import-from #:40ants-doc/docstring #:whitespacep) (:import-from #:40ants-doc/reference) ;; (:import-from #:40ants-doc/page) diff --git a/src/utils.lisp b/src/utils.lisp index f3a88970..29a94bcb 100644 --- a/src/utils.lisp +++ b/src/utils.lisp @@ -4,6 +4,9 @@ (:import-from #:alexandria) (:import-from #:cl-ppcre) (:import-from #:str) + (:import-from #:40ants-doc/docstring + #:whitespacep + #:blankp) (:export #:is-external #:get-package-from-symbol-name @@ -191,19 +194,6 @@ ;;;; String utilities -(eval-when (:compile-toplevel :load-toplevel :execute) - (defparameter *whitespace-chars* - '(#\Space #\Tab #\Return #\Newline #\Linefeed #\Page))) - -(defun whitespacep (char) - (member char *whitespace-chars*)) - -(defun blankp (string) - (every #'whitespacep string)) - -(defun trim-whitespace (string) - (string-trim #.(format nil "~{~A~}" *whitespace-chars*) string)) - ;; TODO: probably replace it with strip-docstring-indentation? (defun strip-longest-common-prefix (string chars &key (first-line-special-p t)) (let ((prefix (longest-common-prefix From ba86f4c57e3d291dfc83571fbdfb7e741ce61146 Mon Sep 17 00:00:00 2001 From: Alexander Artemenko Date: Sun, 5 Dec 2021 19:00:37 +0300 Subject: [PATCH 6/6] Documentation build was fixed. --- README.md | 35 +++++++++++++++++++---------------- src/commondoc/xref.lisp | 5 +++-- 2 files changed, 22 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index f73871e5..7c374b6a 100644 --- a/README.md +++ b/README.md @@ -42,9 +42,9 @@ To introduce hooks for adding new markup languages, and `HTML` themes. Here are features already implemented in this fork: -* Core system `40ANTS-DOC` now has only two dependencies on `NAMED-READTABLES` +* Core system [`40ants-doc`][bdb2] now has only two dependencies on `NAMED-READTABLES` and `PYTHONIC-STRING-READER`. If you want to compile a documentation, load - `40ANTS-DOC-FULL` system which will download such dependencies as markdown + [`40ants-doc-full`][32b2] system which will download such dependencies as markdown parser and more. * Now you don't have to import any locative symbols into your package. Import @@ -199,11 +199,11 @@ choose which. -## [class](2898) `foo-random:foo-random-state` () +## [class](f976) `foo-random:foo-random-state` () -## [reader](b444) `foo-random:state` (foo-random-state) () +## [reader](7ba8) `foo-random:state` (foo-random-state) () Returns random foo's state. @@ -211,24 +211,24 @@ Hey we can also print states! -## [method](6412) `common-lisp:print-object` (object foo-random-state) stream +## [method](3081) `common-lisp:print-object` (object foo-random-state) stream -## [variable](9bdc) `foo-random:*foo-state*` # +## [variable](7c40) `foo-random:*foo-state*` # Much like `*RANDOM-STATE*` but uses the `FOO` algorithm. -## [function](a169) `foo-random:gaussian-random` stddev &key (random-state \*foo-state\*) +## [function](d17b) `foo-random:gaussian-random` stddev &key (random-state \*foo-state\*) Return not a random number from a zero mean normal distribution with `STDDEV`. -## [function](e414) `foo-random:uniform-random` limit &key (random-state \*foo-state\*) +## [function](20fd) `foo-random:uniform-random` limit &key (random-state \*foo-state\*) Return a random number from the between 0 and `LIMIT` (exclusive) uniform distribution. @@ -251,12 +251,12 @@ with `FOO`: ``` [2133]: #x-28FOO-RANDOM-3A-2AFOO-STATE-2A-20-28VARIABLE-29-29 -[2898]: https://github.com/40ants/doc/blob/26d259fe3c44285e327d24b181ad87f2e9910b68/tutorial.lisp#L34 -[b444]: https://github.com/40ants/doc/blob/26d259fe3c44285e327d24b181ad87f2e9910b68/tutorial.lisp#L35 -[6412]: https://github.com/40ants/doc/blob/26d259fe3c44285e327d24b181ad87f2e9910b68/tutorial.lisp#L38 -[9bdc]: https://github.com/40ants/doc/blob/26d259fe3c44285e327d24b181ad87f2e9910b68/tutorial.lisp#L41 -[e414]: https://github.com/40ants/doc/blob/26d259fe3c44285e327d24b181ad87f2e9910b68/tutorial.lisp#L44 -[a169]: https://github.com/40ants/doc/blob/26d259fe3c44285e327d24b181ad87f2e9910b68/tutorial.lisp#L50 +[f976]: https://github.com/40ants/doc/blob/8fcdfabaf4f7e06de256d6a4813ca4a97c617db4/tutorial.lisp#L34 +[7ba8]: https://github.com/40ants/doc/blob/8fcdfabaf4f7e06de256d6a4813ca4a97c617db4/tutorial.lisp#L35 +[3081]: https://github.com/40ants/doc/blob/8fcdfabaf4f7e06de256d6a4813ca4a97c617db4/tutorial.lisp#L38 +[7c40]: https://github.com/40ants/doc/blob/8fcdfabaf4f7e06de256d6a4813ca4a97c617db4/tutorial.lisp#L41 +[20fd]: https://github.com/40ants/doc/blob/8fcdfabaf4f7e06de256d6a4813ca4a97c617db4/tutorial.lisp#L44 +[d17b]: https://github.com/40ants/doc/blob/8fcdfabaf4f7e06de256d6a4813ca4a97c617db4/tutorial.lisp#L50 ```` `MGL-PAX` supported the plain text format which was more readble when viewed from a simple text editor, but I've dropped support for plain text in this fork @@ -268,7 +268,7 @@ and [`40ants-doc/builder:update-asdf-system-docs`][f11d] functions. Last one can even generate documentation for different, but related libraries at the same time with the output going to different files, but with cross-page links being automatically added for symbols -mentioned in docstrings. See `40ANTS-DOC/BUILDER::@GENERATING-DOCUMENTATION` for +mentioned in docstrings. See [`Generating Documentation`][c93a] for some convenience functions to cover the most common cases. Note how `(*FOO-STATE* VARIABLE)` in the [`defsection`][3e7c] form includes its documentation in @@ -278,7 +278,7 @@ definitions tied to symbols. See [`Locative Types`][5922]. The transcript in the code block tagged with `cl-transcript` is automatically checked for up-to-dateness. See -`40ANTS-DOC/TRANSCRIBE::@TRANSCRIPT`. +[`Transcripts`][1f61]. @@ -309,6 +309,8 @@ automatically checked for up-to-dateness. See [6f00]: https://github.com/40ants/doc/discussions [7927]: https://github.com/melisgl/mgl-pax [bdb2]: index.html#x-28-2240ants-doc-22-20ASDF-2FSYSTEM-3ASYSTEM-29 +[32b2]: index.html#x-28-2240ants-doc-full-22-20ASDF-2FSYSTEM-3ASYSTEM-29 +[c93a]: index.html#x-2840ANTS-DOC-2FBUILDER-3A-3A-40GENERATING-DOCUMENTATION-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 [3a45]: index.html#x-2840ANTS-DOC-2FBUILDER-3A-3A-40RENDERING-MULTIPLE-FORMATS-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 [084c]: index.html#x-2840ANTS-DOC-2FBUILDER-3ARENDER-TO-FILES-20FUNCTION-29 [f11d]: index.html#x-2840ANTS-DOC-2FBUILDER-3AUPDATE-ASDF-SYSTEM-DOCS-20FUNCTION-29 @@ -316,6 +318,7 @@ automatically checked for up-to-dateness. See [03a4]: index.html#x-2840ANTS-DOC-2FDOC-3A-3A-40EMACS-INTEGRATION-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 [5922]: index.html#x-2840ANTS-DOC-2FDOC-3A-3A-40LOCATIVE-TYPES-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 [2797]: index.html#x-2840ANTS-DOC-2FDOC-3A-3A-40TODO-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 +[1f61]: index.html#x-2840ANTS-DOC-2FTRANSCRIBE-3A-3A-40TRANSCRIPT-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29 [3e7c]: index.html#x-2840ANTS-DOC-3ADEFSECTION-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29 [ccf9]: index.html#x-28FUNCTION-20-2840ANTS-DOC-2FLOCATIVES-3ALOCATIVE-29-29 [d242]: index.html#x-28VARIABLE-20-2840ANTS-DOC-2FLOCATIVES-3ALOCATIVE-29-29 diff --git a/src/commondoc/xref.lisp b/src/commondoc/xref.lisp index 97f12d5b..baaa3ac2 100644 --- a/src/commondoc/xref.lisp +++ b/src/commondoc/xref.lisp @@ -234,8 +234,9 @@ ;; 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 (= (length (common-doc:text node)) - (length (common-doc:text result))) + (if (and (typep result 'xref) + (= (length (common-doc:text node)) + (length (common-doc:text result)))) result node)) )