docs: turf detailed API diff reports (#293)

I generated these when merging rewrite-clj v0 & rewrite-cljs into
rewrite-clj v1. They were very useful to me, not sure how much so to others.

I used some adoc syntax that happened to work and now longer renders
correctly.

And the scripts I used to generate these reports no longer work.

And, for me, they have served their purpose.

And I'd rather spend my time on other things.

So, I'm turfing them for now.

Closes #132

Author: lread

CHANGELOG.adoc

@@ -34,6 +34,9 @@ A release with known breaking changes is marked with:
 {issue}279[#279] ({lread})
 * `rewrite-clj.paredit/barf-forward` on zipper created with `:track-position? true` now correctly barfs when current node has children
 {issue}245[#245] ({lread}, thanks for the issue {person}p4ulcristian[@p4ulcristian]!)
+* docs
+** Turf API diff reports for now
+{issue}132[#132] ({lread})
 
 === v1.1.47 - 2023-03-25 [[v1.1.47]]
 

bb.edn

@@ -32,7 +32,6 @@
          test-doc          {:task test-doc/-main          :doc "test doc code blocks"}
          test-libs         {:task test-libs/-main         :doc "(list|run|outdated) - verify that libs using rewrite-clj* work with current rewrite-clj"}
          outdated          {:task outdated/-main          :doc "report on outdated Clojure and npm dependencies"}
-         doc-api-diffs     {:task doc-api-diffs/-main     :doc "generate diff docs for rewrite-clj* APIs"}
          doc-update-readme {:task doc-update-readme/-main :doc "honour our contributors in README"}
          cljdoc-preview    {:task cljdoc-preview/-main    :doc "preview what docs will look like on cljdoc, use --help for args"}
          ci-unit-tests     {:task ci-unit-tests/-main     :doc "run/list continuous integration unit tests, use --help for args"}

deps.edn

@@ -125,14 +125,6 @@
            ;; usage -M:sci-test:gen-reflection
            :gen-reflection {:main-opts ["-m" "sci-test.generate-reflection-file"]}
 
-           ;;
-           ;; Document rewrite-clj* differences (needs love!)
-           ;;
-           :diff-apis {:extra-paths ["script/resources"]
-                       :extra-deps {lread/diff-apis {:git/url "https://github.com/lread/diff-apis"
-                                                     :sha "cd8096e0b5e0c0ea4850cb9eafe2d085d8912442"}}
-                       :main-opts ["-m" "diff-apis.main" "projects"]}
-
            ;;
            ;; Deployment
            ;;

doc/02-developer-guide.adoc

@@ -323,29 +323,6 @@ You can optionally:
 * `bb -lint-kondo` to run only clj-kondo linting
 * `bb -lint-eastwood` to run only the eastwood linting
 
-== API diffs
-Rewrite-clj v1's primary goals include remaining compatible with rewrite-clj v0 and rewrite-cljs and avoiding breaking changes.
-
-To generate reports on differences between rewrite-clj v0, rewrite-cljs and
-rewrite-clj v1 APIs, run:
-
-----
-bb doc-api-diffs
-----
-
-WARNING: This task currently needs love, see https://github.com/clj-commons/rewrite-clj/issues/132[#132].
-
-Run this script manually on an as-needed basis, and certainly before any official release.
-Generated reports are to be checked in to version control.
-
-Reports are generated to `doc/generated/api-diffs/` and include manually written notes from `doc/diff-notes/`.
-
-These reports are referenced from other docs, so if you rename files, be sure to search for links.
-
-Makes use of https://github.com/lread/diff-apis[diff-apis].
-Delete `.diff-apis/.cache` if you need a clean run.
-
-
 == Cljdoc Preview
 Before a release, it can be comforting to preview what docs will look like on https://cljdoc.org/[cljdoc].
 

doc/cljdoc.edn

@@ -5,13 +5,7 @@
   ["Developer Guide" {:file "doc/02-developer-guide.adoc"}]
   ["Design" {}
    ["Merging rewrite-clj and rewrite-cljs" {:file "doc/design/01-merging-rewrite-clj-and-rewrite-cljs.adoc"}
-    ["Namespaced Elements" {:file "doc/design/namespaced-elements.adoc"}]]
-   ["API Differences" {}
-    ["rwt-clj v0 vs rwt-cljs" {:file "doc/generated/api-diffs/rewrite-clj-v0-lang-clj-and-rewrite-cljs-lang-cljs.adoc"}]
-    ["rwt-clj v0 vs rwt-clj v1" {:file "doc/generated/api-diffs/rewrite-clj-v0-lang-clj-and-rewrite-clj-v1-lang-clj.adoc"}]
-    ["rwt-cljs vs rwt-clj v1"  {:file "doc/generated/api-diffs/rewrite-cljs-lang-cljs-and-rewrite-clj-v1-lang-cljs.adoc"}]
-    ["rwt-clj v1 clj vs cljs all"  {:file "doc/generated/api-diffs/rewrite-clj-v1-lang-cljs-and-rewrite-clj-v1-lang-clj.adoc"}]
-    ["rwt-clj v1 clj vs cljs public" {:file "doc/generated/api-diffs/rewrite-clj-v1-lang-cljs-and-rewrite-clj-v1-lang-clj-documented-only.adoc"}]]]
+    ["Namespaced Elements" {:file "doc/design/namespaced-elements.adoc"}]]]
   ["Frequently Asked Questions" {:file "doc/03-faq.adoc"}]
   ["Contributing" {:file "CONTRIBUTING.md"}]
   ["Code of Conduct" {:file "CODE_OF_CONDUCT.md"}]

doc/design/01-merging-rewrite-clj-and-rewrite-cljs.adoc

@@ -47,18 +47,6 @@ We will, though, carry over rewrite-cljs's higher level positional functions.
 == Changes
 See link:../../CHANGELOG.adoc[change log].
 
-=== Detailed API diffs
-
-I've used https://github.com/lread/diff-apis[diff-apis] to compare apis.
-Normally I would have excluded any apis tagged with `:no-doc` metadata, but because many folks used undocumented features in rewrite-clj v0 and rewrite-cljs, I have done a complete comparison of all publics - except where noted.
-Each report contains some observations under the "Notes" header.
-
-* link:../generated/api-diffs/rewrite-clj-v0-lang-clj-and-rewrite-cljs-lang-cljs.adoc[rewrite-clj v0 vs rewrite-cljs] API differences between the projects on which rewrite-clj v1 is based.
-* link:../generated/api-diffs/rewrite-clj-v0-lang-clj-and-rewrite-clj-v1-lang-clj.adoc[rewrite-clj v0 vs rewrite-clj v1] how different is rewrite-clj v1 from rewrite-clj v0?
-* link:../generated/api-diffs/rewrite-cljs-lang-cljs-and-rewrite-clj-v1-lang-cljs.adoc[rewrite-cljs vs rewrite-clj v1] how different is rewrite-clj v1 from rewrite-cljs?
-* link:../generated/api-diffs/rewrite-clj-v1-lang-cljs-and-rewrite-clj-v1-lang-clj.adoc[rewrite-clj v1] a look at how cljs and clj sides of rewrite-clj v1 differ
-* link:../generated/api-diffs/rewrite-clj-v1-lang-cljs-and-rewrite-clj-v1-lang-clj-documented-only.adoc[rewrite-clj v1 documented apis only] a look at how cljs and clj sides of rewrite-clj v1 differ for documented apis.
-
 === Feature Differences
 No ability to read from files when using rewrite-clj v1 from ClojureScript.