Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Support simultaneous Clojure & ClojureScript output #220

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Support simultaneous Clojure & ClojureScript output #220

wants to merge 4 commits into from

Commits on Jul 6, 2023

  1. Add support for simultaneous output of >1 language 

    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.

- NO behavioural changes are intended for traditional
  (non-cross-platform) projects.

- See weavejester#216 for detailed feature discussion.
    @ptaoussanis
    ptaoussanis committed Jul 6, 2023
    Configuration menu
    Copy the full SHA
    f88c2d9 View commit details
    Browse the repository at this point in the history

  2. 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.
    @ptaoussanis
    ptaoussanis committed Jul 6, 2023
    Configuration menu
    Copy the full SHA
    f91fdf4 View commit details
    Browse the repository at this point in the history

  3. Add linked platform labels ("clj", "cljs") to var docs 

    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.
    @ptaoussanis
    ptaoussanis committed Jul 6, 2023
    Configuration menu
    Copy the full SHA
    cf166eb View commit details
    Browse the repository at this point in the history

  4. Control language sorting

    @ptaoussanis
    ptaoussanis committed Jul 6, 2023
    Configuration menu
    Copy the full SHA
    cde3ed9 View commit details
    Browse the repository at this point in the history