This page is not created by, affiliated with, or supported by Slack Technologies, Inc.
- # adventofcode (1)
- # announcements (4)
- # beginners (120)
- # calva (5)
- # cider (12)
- # clara (3)
- # cljdoc (48)
- # cljs-dev (33)
- # cljsrn (4)
- # clojure (124)
- # clojure-dev (43)
- # clojure-europe (2)
- # clojure-italy (168)
- # clojure-nl (2)
- # clojure-spec (7)
- # clojure-uk (79)
- # clojurescript (50)
- # core-logic (6)
- # cursive (12)
- # datascript (1)
- # datomic (8)
- # devcards (2)
- # emacs (5)
- # events (2)
- # figwheel-main (6)
- # fulcro (18)
- # graphql (42)
- # hyperfiddle (3)
- # jobs (1)
- # luminus (2)
- # nrepl (5)
- # off-topic (59)
- # onyx (5)
- # parinfer (2)
- # pathom (10)
- # pedestal (2)
- # portkey (3)
- # re-frame (24)
- # reagent (6)
- # reitit (54)
- # remote-jobs (1)
- # ring (5)
- # shadow-cljs (75)
- # spacemacs (35)
- # sql (22)
- # tools-deps (16)
- # unrepl (10)
Yay, finally managed to fix
(integrant.repl/reset) 🎉 https://github.com/cljdoc/cljdoc/commit/139a5a6c8094ef05cde24b93ef942b0882dbb22f
Awesome! Does this mean I don't need to do (integrant.repl/stop) and then (integrant.repl/start)?
you can also add this to your emacs config and then you can just do
(defun integrant-reset () (interactive) (cider-interactive-eval "(integrant.repl/reset)"))
integrant-resetwithout opening the system buffer
Hi! What is the general plan for integration in CI systems of projects to be documented? If I submit a PR to library X and would like to see how my changes will actually look like on http://cljdoc.org later. I.e. a preview. How do you recommend to go about that? See-Also: https://github.com/cljdoc/cljdoc/issues/236
thx, sounds like a plan.
Was also thinking about whether that is something that could be offered as a service. Tell the cljdoc GitHub bot
(go cljdoc) in the PR comments and it will pull the branch, build it into a random version, and provide a link in the GitHub PR. After a week it would delete the stuff again, or when the PR is merged/rejected.
@U368JQA01 that would require knowing how to build every project. unfortunately that can vary greatly from project to project
Maybe the two can work together hand in hand? The project's CI system builds an artifact and stores the link in the GitHub issue and the cljdoc bot picks that up on command and displays it? Or maybe the cljdoc bot can trigger the project's CI system and make it call
ingest towards the cljdoc preview platform?
yeah, there's lots of good stuff that could be done... all a question of the effort / impact ratio 🙂
Yeah, maybe it only makes sense for projects beyond a certain exposition and size.
I think the offline bundle stuff would be a good first step, what do you think?
I'm wondering how to lower the entry bar to producing good documentation. The less services library authors have to setup themselves, the better.
So maybe just offering an installable cljdoc CLI utility (like the [`circleci` tool](https://circleci.com/docs/2.0/local-cli/)) would already be sufficient for most cases, and be less effort for you: Make the current tooling able to respond to
cljdoc run with opening a page in the browser, and you'd be done.
Right but that would require cloning the PR, which you wanted to avoid as far as I understood the workflow you imagined
> Both I and the contributor should be able to look at it (i.e. the result should be available on some web space), to discuss further improvements or catch formatting mistakes. This part?
Probably did not ask the 5 whys when I wrote that... 😞 What I actually meant was more like this: "They should both see the same pages. It would be convenient for them, if those pages were already available on some web space so they would not need to take any other action than looking at it."
In the end the main goal of this process is to "preview this documentation to make sure it contains no formatting issues and renders as intended" (since how it renders influences how it is perceived by readers, which in turn can guide or mislead their understanding of the text).
In the beginning I thought that uploading it to a web space would be convenient enough, but now I think that not many people operate web servers or want to pay for one, so that might not actually be as convenient as I thought initially.
I am exploring multiple routes to tackle the underlying problem, in order to figure out what works best. What would definitely be inconvenient would be if one had to git clone cljdoc, start the server, cd to the PR checkout, ingest the docs, open the web browser, navigate to the right spot. Too many steps, too many locations to do something. Hence the idea of shoving this off to a CI, which many projects are probably already using.
I also think the /download + artifact route might be most feasible/easy for a first version
Can cljdoc push the offline docs directly to S3 or similar? That might be convenient enough for many people to integrate it into their CI process. Though you probably would not want every PR to be made public like that, so you'd still need a gatekeeping process, like the
(go cljdoc) bot... I think the best first step is to just make the local preview process more convenient using a wrapper shell script like the circleci script, which would just wrap
java -jar cljdoc.jar or
clj -m cljdoc.main or similar, just to allow people to easily use cljdoc locally as a tool.
I think we could probably make a script that - downloads cljdoc - runs ingest - builds offline bundle
Re: S3/CircleCI: I'm thinking about how to make it easy to view the result. Having the artifact available for download is nice, but you also need to deploy it somewhere. Maybe it's necessary to tinker with different approaches for a while to figure out what works in practice for most projects and what does not.
> need to deploy it somewhere
why if reviewers can just download the artifact and view
index.html — shouldn't that work? Did you take a look at an offline bundle? they work without servers
Plain convenience. Having the CI attach a link to a PR that people just have to click to preview the change is more convenient that having to download a tarball, extract it, open a browser.
I think of this as an 80/20 kind of thing. Making the docs available at a remote location without any extra step is 100% UX. Downloading a tarball and opening a file inside it is 80%. The 20% to get to 100% require more effort than to get to 80%
yes, very much. But I don't think I'll be paid to do this, so I'll do it in my free time instead.
I also created a milestone (experimenting with that really) for previews related stuff: https://github.com/cljdoc/cljdoc/milestone/2
I'd suggest also add a "create easy
cljdoc run command" task, for the other approach -- what do you think about that? Basically have
./script/cljdoc downloadable and able to pull a released cljdoc JAR, so it can work standalone?
There’s no cljdoc jar yet but we can write scripts that download and run cljdoc