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

Docs fail to be imported into cljdoc #353

Closed
holyjak opened this issue Sep 6, 2022 · 2 comments
Closed

Docs fail to be imported into cljdoc #353

holyjak opened this issue Sep 6, 2022 · 2 comments
Labels
enhancement ideas welcome pull requests welcome

Comments

@holyjak
Copy link

holyjak commented Sep 6, 2022

CljDoc is a popular single source of docs for clojure libraries, integrated with desktop doc viewers such as Dash. Thus it would be very nice if it could also display timbre's docs. Currently https://cljdoc.org/d/com.taoensso/timbre/5.2.1 reads "import failed" due to the error:

ClassNotFoundException: android.util.Log, compiling:(taoensso/timbre/appenders/3rd_party/android_logcat.clj:38:20)

Perhaps the tips in https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc#getting-dependencies-right might help? (I.e. adding the android lib as a "provided" optional dependency?)

I am sure the cljdoc people will be happy to help via Slack or an issue.

Thank you!
@ptaoussanis
Copy link
Member

@holyjak Hi Jakub, thanks for bringing this to my attention!

It'd be great to get Timbre working with CljDoc, though it's not immediately obvious to me what'd be needed to get it working.

I don't believe that "provided" would help here. If CljDoc tries to load all namespaces, ultimately I guess it'd either need to have those namespaces successfully load - or it'd need to be able to gracefully skip a namespace that can't be successfully loaded. To successfully load that Android appender namespace, I expect the Android the Android platform would actually need to be present.

I could be mistaken though!

I won't have the opportunity to look into this in detail right now, but would be very happy to see a PR if you or someone else can confirm a solution from Timbre's end.

If we can't think of anything to do from Timbre's end, an alternative might be to see if it'd be possible for CljDoc to skip namespaces that it can't load. Not sure what downsides that might involve, assuming it's possible.

@ptaoussanis
Copy link
Member

Think I've found a sort of workaround for this, by moving all the community appender stuff into a different source folder that's excluded by Leiningen's default profiles.

Change will be included in a forthcoming release.

Thanks again for pinging about this 👍

ptaoussanis added a commit that referenced this issue Oct 19, 2022
@ptaoussanis
[nop] [#353] Exclude community code from default Lein profile
626feee 
This prevents community code with strange dependencies and/or
environment expectations (e.g. Android) from interfering with
builds, cljdoc, etc.

Not an ideal solution, but probably good enough for now - and certainly better
than the previous situation.
ptaoussanis added a commit that referenced this issue Oct 19, 2022
@ptaoussanis
[nop] [#353] Re-introduce community code, under dedicated profile
0bd4a5d
ptaoussanis added a commit that referenced this issue Oct 20, 2022
@ptaoussanis
[nop] [#353] Exclude community code from default Lein profile
abb7464 
This prevents community code with strange dependencies and/or
environment expectations (e.g. Android) from interfering with
builds, cljdoc, etc.

Not an ideal solution, but probably good enough for now - and certainly better
than the previous situation.
ptaoussanis added a commit that referenced this issue Oct 20, 2022
@ptaoussanis
[nop] [#353] Re-introduce community code, under dedicated profile
bcc1348
ptaoussanis added a commit that referenced this issue Oct 22, 2022
@ptaoussanis
[mod] [BREAKING] [#322 #353] Reorganise community appenders
f11e8d4 
Changes include:

  - [#322] Rename `3rd-party` -> `community`
  - [#353] Exclude from default Lein profiles to help prevent community
    code with strange dependencies and/or environment expectations
    (e.g. Android) from interfering with builds, cljdoc, etc.
ptaoussanis added a commit that referenced this issue Oct 23, 2022
@ptaoussanis
[mod] [BREAKING] [#322 #353] Reorganise community appenders
1c9fbb4 
Before this commit:
  Community appender namespaces: `taoensso.timbre.appenders.3rd-party.X`

After this commit:
  Community appender namespaces: `taoensso.timbre.appenders.community.X`.

This is a BREAKING change for you iff:
  You're using any of the included community appenders.
  In this case, just change `3rd-party` in your ns imports to `community`.

Motivation for change:

  The `3rd-party` namespace segment beginning with a numeric has long
  caused minor issues with tooling, etc. (e.g. #322).

  Took the opportunity to also exclude community code from the default
  Lein profiles to help prevent community code with strange dependencies
  and/or environment expectations (e.g. Android platform) from interfering
  with builds, cljdoc, etc.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement ideas welcome pull requests welcome
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@ptaoussanis @holyjak