Add support for simultaneous Clojure & ClojureScript output, supporting fixes #217
+257
−77
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Author: @martinklepsch Codox previously did two passes to also read macros for ClojureScript. This is actually no longer necessary with more recent versions of ClojureScript. cljdoc@3079986
Author: @martinklepsch For some reason the list? check wasn't enough to remove 'quote and I ended up with 'quote in arglists. seq? did the trick (and might be more appropriate anyways?). cljdoc@25b01ae
Author: @martinklepsch I noticed some issues (+ more details[2]) with the new CLJS version. Turns out setting *analyze-deps* to false was never really supported for macro-containing namespaces and we just got lucky[3]. Fixes [1] [1] cljdoc/cljdoc#201 [2] https://gist.github.com/martinklepsch/9f885feb061ec3f03f365e22d0d9bf5b [3] https://clojurians-log.clojureverse.org/cljs-dev/2018-11-09/1541786231.245300 cljdoc@e0cd269
Author: @martinklepsch When there are multiple files (e.g. .clj and .cljc) for a namespace Codox would analyse those namespaces twice returning the analysis result twice as well. cljdoc@3f2ea84 cljdoc/cljdoc#155
Author: @ptaoussanis - This implementation attempts to be minimally invasive. Most of the logical changes are within `html/write-index` and `html/write-namespaces`, where a special path is introduced for "cross-platform" projects (= language `:both`). - NO behavioural changes are intended for traditional (non-cross-platform) projects. - See weavejester#216 for detailed feature discussion.
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 {:language :both} then: {:base-language nil} => ".clj", ".cljs" file extensions {: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 {:language :both}, but don't want to break pre-existing links in the wild. In this case, Foo's authors can use the following opts: {:language :both :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.
Author: @ptaoussanis Note that this commit introduces new classes to `default.css` used (only) by "cross-platform" projects. This means: - NO behavioural changes are intended for non-cross-platform projects. - Cross-platform projects WILL require a theme that includes the new CSS classes.
Author: @ptaoussanis Small change that hopefully contributes to a more modern look
Owner
|
Thanks for the PR! I think we'll need to break this up to be a little to be manageable: PR 1. Fix ClojureScript issues: df7ddcb, 370ef9e and ebfece3. If this sounds like too much of a pain, I can handle the first two PRs myself, as I probably should have done that a while ago. Rather than |
This was referenced Jul 6, 2023
Author
|
👍 Closing, this work is now spread across the following PRs:
Have updated the relevant code 👍 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes #216 and includes all fixes from #179 (these are relevant here).
Live examples of the current cross-platform output:
High-level notes
Implementation notes
{:language :both}support should not affect those using{:language :clojure}or{:language :clojurescript}.projectmap for conveying relevant internal state. I'm satisfied with this approach, but drawing attention to it in case you feel differently.html/write-documentscode, and haven't tested it specifically - but I see no reason why this PR should cause any problems with it.Thanks a lot for your time & effort.
I know big PRs like this can be time-consuming to properly review. Just ping if I can answer any questions, etc.
Cheers :-)