From f91fdf41a67fab855db2f73c6c27f40379b70b55 Mon Sep 17 00:00:00 2001
From: Peter Taoussanis <peter@taoensso.com>
Date: Tue, 4 Jul 2023 18:45:56 +0200
Subject: [PATCH] Add support for advanced `:base-language` option

Author: @ptaoussanis

This is an advanced option to help prevent any broken doc links
when upgrading a project's docs from single language to dual language.

In this case, :base-language can be set to the previous (single)
language for which doc links may already exist in the wild.

In detail, if cross-platform project then:

  {:base-language nil}            => ".clj", ".cljs" file extensions ; Default
  {:base-language :clojure}       => nil,    ".cljs" file extensions
  {:base-language :clojurescript} => ".clj", nil     file extensions

For example:

  Library Foo previously used {:language :clojure} (either because
  it was Clojure only, or because of limitations in Codox).

  Various links to Foo's Codox documentation now exist in the wild.

  Foo's authors want to change to cross-platform, but don't
  want to break pre-existing links in the wild.

  In this case, Foo's authors can use the following opts:
    {:language #{:clojure :clojurescript}
     :base-language :clojure}

  This will produce files like the following:
    com.foolib.html      ; For Clojure       platform
    com.foolib.cljs.html ; For ClojureScript platform

  Any pre-existing links will successfully point to the same
  (Clojure) docs they did previously.
---
 codox/src/codox/writer/html.clj | 33 +++++++++++++++++++++------------
 1 file changed, 21 insertions(+), 12 deletions(-)

diff --git a/codox/src/codox/writer/html.clj b/codox/src/codox/writer/html.clj
index ab080db..3486d4f 100644
--- a/codox/src/codox/writer/html.clj
+++ b/codox/src/codox/writer/html.clj
@@ -147,20 +147,26 @@
      (markdown-to-html doc project ns))])
 
 (defn- language-info
-  [language]
-  (when language
-    (case language
-      :clojure       {:ext "clj",  :filename-suffix ".clj",  :name "Clojure"}
-      :clojurescript {:ext "cljs", :filename-suffix ".cljs", :name "ClojureScript"}
-      (ex-info (str "Unexpected language: `" language "`")
-        {:language language}))))
+  ([language]
+   (when language
+     (case language
+       :clojure       {:ext "clj",  :filename-suffix ".clj",  :name "Clojure"}
+       :clojurescript {:ext "cljs", :filename-suffix ".cljs", :name "ClojureScript"}
+       (ex-info (str "Unexpected language: `" language "`")
+         {:language language}))))
+         
+  ([language base-language]
+   (when-let [info (language-info language)]
+     (if (= language base-language)
+       (assoc info :filename-suffix "")
+       info))))
 
 (defn- index-filename [language]
   (str "index" (:filename-suffix (language-info language)) ".html"))
 
 (defn- ns-filename [namespace]
   (str (:name namespace)
-    (:filename-suffix (language-info (:language namespace)))
+    (:filename-suffix (language-info (:language namespace) (:base-language namespace)))
     ".html"))
 
 (comment
@@ -517,8 +523,11 @@
     (.mkdirs (io/file output-dir dir))))
 
 (defn- cross-platform-namespaces
-  [namespaces language]
-  (map #(assoc % :language language)
+  [namespaces language base-language]
+  (map
+    #(assoc %
+       :language language
+       :base-language base-language)
     (get namespaces language)))
 
 (defn- write-index [output-dir project]
@@ -527,7 +536,7 @@
     (when cross-platform?
       ;; Write an index file for each language
       (doseq [language (:languages project)]
-        (let [namespaces (cross-platform-namespaces namespaces language)
+        (let [namespaces (cross-platform-namespaces namespaces language (:base-language project))
               project
               (assoc project
                 :namespaces namespaces
@@ -550,7 +559,7 @@
     (if cross-platform?
       ;; Write namespace files for each language
       (doseq [language (:languages project)]
-        (let [namespaces (cross-platform-namespaces namespaces language)]
+        (let [namespaces (cross-platform-namespaces namespaces language (:base-language project))]
           (doseq [namespace namespaces]
             (let [project (assoc project
                             :namespaces namespaces