Supported documentation building for projects cloned as git submodules.

full/doc.lisp

@@ -114,6 +114,8 @@
     "
 <table class=\"badges\">
 <tr>
+<td><a href=\"https://github.com/40ants/ai-badges\"><img src=\"https://img.shields.io/badge/SAFE-HAND%20MADE%20CODE-32CD32\"/></a></td>
+
 <td><a href=\"https://github.com/40ants/doc/actions/workflows/ci.yml\"><img src=\"http://github-actions.40ants.com/40ants/doc/matrix.svg?only=ci.run-tests\"/></a></td>
 
 <td><a href=\"https://github.com/40ants/doc/actions/workflows/linter.yml\"><img src=\"http://github-actions.40ants.com/40ants/doc/matrix.svg?only=linter.linter\"/></a></td>

full/github.lisp

@@ -9,8 +9,12 @@
                 #:reference-object)
   (:import-from #:40ants-doc/source-api)
   (:import-from #:cl-ppcre)
-  (:import-from #:str)
+  (:import-from #:str
+                #:trim
+                #:split)
   (:import-from #:alexandria
+                #:read-file-into-string
+                #:length=
                 #:starts-with-subseq)
   (:import-from #:40ants-doc/reference-api
                 #:*source-uri-fn*
@@ -108,23 +112,60 @@
               for ASDF system~% ~A. Links to github will not be generated."
               (asdf:component-name (asdf:registered-system asdf-system))))))
 
+
+(defun read-git-dir-link (pathname)
+  "When system is cloned as a submodule, then instead of .git/ directory there is a file .git
+   with a link like this:
+
+   ```
+   gitdir: ../../.git/modules/libs/ai-agents
+   ```
+
+   This function reads such file and returns a new pathname pointing to the real git dir.
+"
+  (loop with content = (read-file-into-string pathname)
+        with lines = (split #\Newline content)
+        for line in lines
+        for trimmed = (trim line)
+        for splitted = (unless (string= trimmed "")
+                         (split #\: trimmed :limit 2))
+        for key = (when (length= 2 splitted)
+                    (first splitted))
+        when (and key
+                  (string= key "gitdir"))
+          do (return (merge-pathnames (uiop:ensure-directory-pathname
+                                       (trim (second splitted)))
+                                      pathname))))
+
+
 (defun asdf-system-git-version (system)
   (check-type system asdf:system)
 
   (let* ((git-dir
            (merge-pathnames (make-pathname :directory '(:relative ".git"))
-                            (asdf:system-relative-pathname system ""))))
-    (if (probe-file git-dir)
-        (git-version git-dir)
-        nil)))
+                            (asdf:system-relative-pathname system "")))
+         (git-dir
+           (when git-dir
+             (probe-file git-dir)))
+         (git-dir
+           (when git-dir
+             (cond
+               ((uiop:directory-pathname-p git-dir)
+                git-dir)
+               (t
+                (read-git-dir-link git-dir))))))
+    (if git-dir
+      (git-version git-dir)
+      nil)))
+
 
 (defun git-version (git-dir)
   (let ((head-string (read-first-line
                       (merge-pathnames (make-pathname :name "HEAD") git-dir))))
     (if (starts-with-subseq "ref: " head-string)
-        (let ((ref (subseq head-string 5)))
-          (values (read-first-line (merge-pathnames ref git-dir)) ref))
-        head-string)))
+      (let ((ref (subseq head-string 5)))
+        (values (read-first-line (merge-pathnames ref git-dir)) ref))
+      head-string)))
 
 (defun read-first-line (filename)
   (with-open-file (stream filename)

full/utils.lisp

@@ -549,33 +549,72 @@
     (reverse translated)))
 
 
+(defun normalize-system-name (system-name)
+  (cond
+    ((consp system-name)
+     (cond
+       ((eql (first system-name)
+             :feature)
+        (when (member (second system-name)
+                      *features*)
+          (let ((new-dep (third system-name)))
+            (cond
+              ((and (consp new-dep)
+                    (eql (first new-dep)
+                         :require))
+               ;; Usually :require dependencies
+               ;; load native lisp implementation modules,
+               ;; so we don't need to list them as external dependencies.
+               nil)
+              (t
+               system-name)))))
+       (t
+        (error "Deps ok kind ~S are not supported"
+               (first system-name)))))
+    (t
+     system-name)))
+
+
 (defun external-dependencies (system-name) 
   (let ((primary-name (asdf:primary-system-name system-name))
         (processed nil))
     (labels ((rec (system-name &optional collected)
-               (cond
-                 ((member system-name processed
-                          :test #'string-equal)
-                  collected)
-                 (t
-                  (push system-name processed)
-                  ;; (format t "Processing ~S system~%" system-name)
+               (let ((system-name
+                       (normalize-system-name system-name)))
+                 (cond
+                   ((null system-name)
+                    (values))
+                   ((member system-name processed
+                            :test #'string-equal)
+                    collected)
+                   (t
+                    (push system-name processed)
+                    ;; (format t "Processing ~S system~%" system-name)
 
-                  (let* ((system (asdf:registered-system system-name))
-                         (dependencies (asdf/system:system-depends-on system)))
-                    (loop for dep in dependencies
-                          for dep-primary = (asdf:primary-system-name dep)
-                          unless (or (string-equal primary-name dep-primary)
-                                     (member dep collected
-                                             :test #'string-equal))
-                          collect dep into new-deps
-                          finally (setf collected
-                                        (append new-deps
-                                                collected)))
-                    (loop for dep in dependencies
-                          do (setf collected
-                                   (rec dep collected)))
-                    collected)))))
+                    (let* ((system (asdf:registered-system system-name))
+                           (dependencies (asdf/system:system-depends-on system)))
+                      (loop for dep in dependencies
+                            for normalized-dep = (normalize-system-name dep)
+                            for dep-primary = (when normalized-dep
+                                                (asdf:primary-system-name normalized-dep))
+                            unless (or (null dep-primary)
+                                       (string-equal primary-name dep-primary)
+                                       (member dep-primary new-deps
+                                               :test #'string-equal)
+                                       (member dep-primary collected
+                                               :test #'string-equal))
+                              collect dep-primary into new-deps
+                            finally
+                               (when new-deps
+                                 ;; (format t "Appending ~S to ~S~%" new-deps collected)
+                                 (setf collected
+                                       (append new-deps
+                                               collected))))
+
+                      (loop for dep in dependencies
+                            do (setf collected
+                                     (rec dep collected)))
+                      collected))))))
       (sort (rec system-name)
             #'string<))))
 

qlfile.lock

@@ -1,8 +1,8 @@
 ("quicklisp" .
  (:class qlot/source/dist:source-dist
-  :initargs (:distribution "http://beta.quicklisp.org/dist/quicklisp.txt" :%version :latest)
-  :version "2024-10-12"))
+  :initargs (:distribution "https://beta.quicklisp.org/dist/quicklisp.txt" :%version :latest)
+  :version "2026-01-01"))
 ("ultralisp" .
  (:class qlot/source/dist:source-dist
-  :initargs (:distribution "http://dist.ultralisp.org" :%version :latest)
-  :version "20241210203500"))
+  :initargs (:distribution "https://dist.ultralisp.org" :%version :latest)
+  :version "20260410160500"))

src/changelog.lisp

@@ -155,6 +155,9 @@
                               "CLEAN-URLS"
                               ;; These objects are not documented yet:
                               "40ANTS-DOC/COMMONDOC/XREF:XREF"))
+  (0.26.0 2026-04-11
+          "* Supported documentation building for projects cloned as git submodules.
+           * Fixed external dependencies listing in case if some deps use :require.")
   (0.25.1 2025-09-13
           "* New package 40ants-doc/mito now exports `fixed-dao-table-class` class which should be used instead of Mito's `dao-table-class`.")
   (0.25.0 2025-09-13

src/core.lisp

@@ -7,8 +7,11 @@
   (:import-from #:40ants-doc/object-package)
   (:import-from #:40ants-doc/docstring
                 #:strip-docstring-indentation)
-  (:import-from #:serapeum
-                #:soft-list-of)
+  ;; We specially do not use soft-list-from-serapeum here
+  ;; to protect core of 40ants-doc from Serapeum and it's transitive
+  ;; dependencies
+  ;; (:import-from #:serapeum
+  ;;               #:soft-list-of)
   (:export #:defsection
            #:exportable-locative-type-p
            #:section
@@ -213,6 +216,16 @@
                         :ignore-packages (list
                                           ,@(eval ignore-packages)))))))
 
+(deftype simple-list-of (type)
+  "A soft constraint for the elements of a list.
+
+Only first element is checked.
+"
+  `(or null
+       (cons ,type
+             t)))
+
+
 (defclass section ()
   ((name
     :initarg :name
@@ -252,13 +265,13 @@
     :documentation "A list of strings with URLs of other system's documentation.")
    (ignore-words
     :initarg :ignore-words
-    :type (soft-list-of string)
+    :type (simple-list-of string)
     :initform nil
     :reader section-ignore-words
     :documentation "A list of strings to not warn about.")
    (ignore-packages
     :initarg :ignore-packages
-    :type (soft-list-of string)
+    :type (simple-list-of string)
     :initform nil
     :reader section-ignore-packages
     :documentation "A list of strings denoting package names to not warn about."))

test/data/baseline/search/index.html

@@ -4,28 +4,18 @@
       content="width=device-width, initial-scale=1">
   <title>Search Page</title>
   <link rel=alternate
-        href=https://40ants.com/doc/changelog.xml
-        type=application/rss+xml>
-  <link rel=stylesheet type=text/css
-        href=../theme.css>
-  <script type=text/javascript src=../jquery.js></script>
-  <script type=text/javascript src=../toc.js></script>
-  <link rel=stylesheet type=text/css
-        href=../highlight.min.css>
-  <script type=text/javascript
-          src=../highlight.min.js></script>
-  <script type=text/javascript>hljs.highlightAll();</script>
-  <script type=text/javascript>
-             MathJax = {
-               tex: {
-                 inlineMath: [['$','$']],
-                 processEscapes: true
-               }
-             };
-        </script>
-  <script type=text/javascript
-          src=https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js></script>
-  <script type=text/javascript>$(document).ready(function() {$('a:has(img)').css('border-bottom', 'none')})</script>
+        href="https://40ants.com/doc/changelog.xml"
+        type="application/rss+xml">
+  <link rel=stylesheet type="text/css"
+        href="../theme.css">
+  <script type="text/javascript" src="../jquery.js"></script>
+  <script type="text/javascript" src="../toc.js"></script>
+  <script type="text/javascript">$(document).ready(function() {$('a:has(img)').css('border-bottom', 'none')})</script>
+  <link rel=stylesheet type="text/css"
+      href="../highlight.min.css">
+  <script type="text/javascript"
+          src="../highlight.min.js"></script>
+  <script type="text/javascript">hljs.highlightAll();</script>
  </head>
  <body>
   <div class=page><div class=sidebar><div class=header><form class=search method=GET action="">
@@ -37,17 +27,17 @@
     </div><div class=footer>
      <a href="https://40ants.com/doc">[generated by 40ANTS-DOC]</a>
     </div>
-   </div><div class=content role=main><script>
+   </div><div class=content role=main><script type="text/javascript">
 var DOCUMENTATION_OPTIONS = {
-    URL_ROOT: &#39;&#39;,
-    VERSION: &#39;5.0.0+&#39;,
-    LANGUAGE: &#39;en&#39;,
+    URL_ROOT: '',
+    VERSION: '5.0.0+',
+    LANGUAGE: 'en',
     COLLAPSE_INDEX: false,
-    BUILDER: &#39;html&#39;,
-    FILE_SUFFIX: &#39;.html&#39;,
-    LINK_SUFFIX: &#39;.html&#39;,
+    BUILDER: 'dirhtml',
+    FILE_SUFFIX: '.html',
+    LINK_SUFFIX: '.html',
     HAS_SOURCE: true,
-    SOURCELINK_SUFFIX: &#39;.txt&#39;,
+    SOURCELINK_SUFFIX: '.txt',
     NAVIGATION_WITH_KEYS: false
 };
 </script>
@@ -60,4 +50,4 @@
    </div>
   </div>
  </body>
-</html>
+</html>