[Feature request] Support simultaneous Clojure & ClojureScript output

[ptaoussanis]

Hi James, thanks so much for all the awesome work on Codox - and so many other libraries over the years! 🙏 🙏

No urgency, but when you get an opportunity would appreciate your input on this.

I author quite a few libraries that include both a Clojure and ClojureScript API.

My understanding is that currently Codox can generate either:

1. Documentation for {:language :clojure}, or
2. Documentation for {:language :clojurescript} (which includes relevant Clojure macros).

But for the kinds of cross-platform libraries I'm talking about (e.g. Encore, Timbre, Sente, etc.) - it'd actually be ideal if Codox could generate API docs from the perspective of both Clojure and ClojureScript users.

From what I can tell, cljdoc handles these cases by just combining everything together. For example, here you'll see clj, cljs, and clj/s vars all visible from the same list.

My 2c is it'd actually be better (and I suspect simpler) to instead require users to make a top-level choice: i.e. to browse the Clojure documentation, or the ClojureScript documentation.

I'd just like to have both available to the user.

A few motivations for this approach:

• No need to consider the layout and style when differences occur between clj/s.
• No trouble when there's disagreement in args and/or docstrings across platforms.
• I believe that when viewing documentation, most users will have in mind a particular platform - so filtering to show only that platform should help cut down on noise.
• My hope/expectation is that something like this might not be too difficult to implement?

Does this make sense / seem reasonable?

Thanks so much for your time! Cheers :-) - Peter

[weavejester]

Yes, it should be relatively straightforward. Both Clojure and ClojureScript reader data could be merged before being passed to the writer. Ideally we'd also want some identifier to distinguish which functions are Clojure and ClojureScript.

[ptaoussanis]

Thanks a lot for the prompt response! I'll aim then to try take a closer look at this in the next few weeks, and will update with a PR if I can figure out the details.

BTW, I'll note that I think that Codox still has a really important role to fulfil in the Clojure ecosystem. Projects like cljdoc are awesome, but (IMO) offer significantly different tradeoffs. I'm personally really happy that Codox is still around and kicking after so many years of service to the community 👍

Happy weekend, cheers! :-)

[ptaoussanis]

Okay, took a quick look at this.

I propose the following:

1. We add support for the :language value to be a set, e.g. #{:clojure :clojurescript}.
2. If and only if >1 language is selected, we introduce new behaviour:
3. The top-level index shall no longer contain namespace output, but only links to "Clojure" and "ClojureScript" sections. [Figure A]
4. Clicking "Clojure" or "ClojureScript" will now go to platform-specific index pages that contain namespace output. [Figure B]
5. The file structure includes "clojure" and "clojurescript" dirs. [Figure C]

Figure A

Figure B

Figure C

---

Notes

• We don't try to intermingle the Clojure and ClojureScript documentation. I believe that would cause unnecessary noise and possible confusion - especially when different platforms may have different arguments and/or docstrings.
• We do NOT change the file structure or output unless >1 language is provided, meaning we don't break the URLs/links of any existing Codox users. Anyone using Codox for a single language won't see any change to their generated documentation.

@weavejester Does this appear reasonable to you, James? If so, I'll prepare a PR when I get an opportunity.

Thanks again for your time + input. Cheers! :-)

[ptaoussanis]

Update: have a potential implementation ready, see here for example output.

Notes

• Output is identical (unmodified) if {:language :clojure} or {:language :clojurescript}. So will not break any pre-existing links.
• If {:language :both} then:
  • The top-level index now hides "Namespaces", and instead shows "Platforms". [Figure A]
  • Language-level indexes are now present. [Figure B]
• To simplify theming and prevent any theme/transform breaks, I've kept a flat file hierarchy. [Figure C]
• I intentionally avoided intermingling Clojure and ClojureScript docs. I believe that causes unnecessary noise and possible confusion - especially when different platforms may have different arguments, docstrings, and/or namespaces.

[Figure A]

[Figure B]

[Figure C]

Next steps

Just let me know if you're happy with this approach and I'll prepare a PR. The code change is reasonable small and self-contained, I don't believe it should break any custom writers or themes, etc.

But zero pressure or urgency, I'm also quite happy to use a fork for this.

Thanks again! Cheers :-)

[weavejester]

Thanks for the detailed proposal!

I think the "Platforms" section could use a little adjustment. Previously you click a link on the sidebar, and it takes you to a specific page. There's only one thing selected. But in this case the user would be selecting two things, platform and namespace, or one thing, the index or some other documentation page.

One way to get around this is to treat the platform as a top-level folder, adding it above the namespace hierarchy. The problem with treating it as a folder is that I can see it being difficult to navigate for long hierarchies. For example:

• Clojure
  • example
    • core
    • protocols
    • readers
    • edn
    • json
    • bson
    • writers
    • html
    • markdown
  • ClojureScript

Even if the ClojureScript folder is collapsed when accessing Clojure, and vice versa, you'd still need to scroll past all the Clojure namespaces to reach the ClojureScript part.

The alternative is to have it as a filter, similar to to how you've set it up, but we can make it more explicit by giving it a style that indicates it's a toggle.

Or perhaps a tab bar:

The tabs might be a better design language, as a user expects the view below a tab bar to change when they change tabs. With a toggle, the effect is more ambiguous.

What are your thoughts?

[ptaoussanis]

Thanks for the detailed proposal!

You're very welcome, thanks for the quick + detailed response!

What are your thoughts?

In principle my ordered preferences would be:

1. Tab bar
2. Pill bar
3. Current implementation
4. Language-nested namespace hierarchy

I'm not a fan of #4 (language-nested ns hierarchy), since part of my motivation in proposing to keep Clj and Cljs docs separate is the desire to reduce noise. For libraries like Timbre, there may be large ns hierarchies that are very different between platforms. And adding your point about possible deeply-nested hierarchies and potential issues like #211, I'd vote for avoiding that.

So that leaves #1-3:

• #3 seems the least invasive change.
• #1 seems conceptually the clearest, but might need the biggest layout change (it's not obvious to me where we'd put tabs in the current design).
• #2 seems like a decent middle-ground (I suspect we could squeeze the pills into a slightly enlarged header).

My 2c: #3 is probably sufficient if we want to keep things quick+easy. It feels okay in practice (demo), and it's ~ready to go.

Since #1-3 are all conceptually compatible (modal), we could also always do this in phases: i.e. first get the basic functionality in via #3 - then consider later work to improve the layout.

The important thing to get right at this point IMO would be the API, and the file/link structure - since that'd hurt to break later on.

I'm neutral on the layout, happy to go with your preference if you have something specific in mind 👍

BTW I've also added language labels to the var docs, with inline links to jump between languages when relevant:

In this screenshot: the "Clojure" var is selected. Clicking "Cljs" will jump to the same var in the ClojureScript namespace.

[ptaoussanis]

Update: I'm experimenting with language selection in the header:

Still polishing a few things, I'll open a PR for your review once I'm happy with the design 👍