Clojurians Log v2

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.

@devurandom 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?

Sure. At least if the amount of required effort is low.

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?

yes

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.

yes, I'm in favor of utilizing CI for this

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.

You don't need S3 on CircleCI: https://www.circleci.com/docs/2.0/artifacts

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%

good point

@urzds maybe you wanna take this on? https://github.com/cljdoc/cljdoc/issues/244

"take on" as in be assigned? If so, please assign @devurandom instead.

take on as in "work on" 😄

just wondering since it sounded like you wanted to help with this

I can't assign you so you'll have to do that yourself I guess 🙂

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

Anyway, I've highlighted myself here, so I'll pick this up when I'm at home.

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

Or package a jar properly. But that’s a little tricky as well since there are multiple isolated environments