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..7c374b6a 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`][bdb2] 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`][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
- 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](f976) `foo-random:foo-random-state` ()
-## [reader](f58b) `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](967c) `common-lisp:print-object` (object foo-random-state) stream
+## [method](3081) `common-lisp:print-object` (object foo-random-state) stream
-## [variable](8b8d) `foo-random:*foo-state*` #
+## [variable](7c40) `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](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](08b1) `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,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
+[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
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 [`Generating Documentation`][c93a] 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].
+[`Transcripts`][1f61].
@@ -299,30 +299,29 @@ 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
+[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
+[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
+[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
* * *
###### [generated by [40ANTS-DOC](https://40ants.com/doc/)]
diff --git a/src/changelog.lisp b/src/changelog.lisp
index 69e14028..aa7f8f4d 100644
--- a/src/changelog.lisp
+++ b/src/changelog.lisp
@@ -143,6 +143,12 @@
"*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.
+ * Added EXTERNAL-LINKS argument to DEFSECTION 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
+ 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/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/page.lisp b/src/commondoc/page.lisp
index fe40f0b7..303c58fb 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)))
(when (and (typep obj 'symbol)
(not (is-external obj))
- (not (typep obj 'keyword)))
+ (not (typep obj 'keyword))
+ (not (ignored-in-package obj package)))
(warn "Symbol ~S is documented but not exported from it's package."
obj))))
node))
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 6bc78eb4..baaa3ac2 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,7 +203,7 @@
*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
@@ -208,18 +212,36 @@
;; symbol extraction inside code blocks
(when (typep node
'common-doc:code-block)
- (setf inside-code-block t)))
+ (setf inside-code-block t))
+ (when (typep node
+ 'common-doc:code)
+ (setf inside-inline-code t)))
(go-up (node)
(when (typep node
'common-doc:code-block)
- (setf inside-code-block nil)))
+ (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*)
- 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 (and (typep result 'xref)
+ (= (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/core.lisp b/src/core.lisp
index 7cd7ff23..65ea242d 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/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/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/ignored-words.lisp b/src/ignored-words.lisp
index d54d3b47..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,17 +20,26 @@
(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*)))
(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)
+ "Checks if given symbol or string is ignored in a package."
(member symbol-or-string
(gethash package *package-ignore-words*)
:test #'equal))
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))))))
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 d28196d1..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,7 @@
;;;; 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
string chars :first-line-special-p first-line-special-p)))