Fork me on GitHub
#cljdoc
<
2018-11-27
>
martinklepsch20:11:44

Yay, finally managed to fix (integrant.repl/reset) ๐ŸŽ‰ https://github.com/cljdoc/cljdoc/commit/139a5a6c8094ef05cde24b93ef942b0882dbb22f

๐Ÿ™Œ 1
๐ŸŽ‰ 1
martinklepsch20:11:20

(entirely my fault that it didn't work in the first place)

Daw-Ran Liou21:11:34

Awesome! Does this mean I don't need to do (integrant.repl/stop) and then (integrant.repl/start)?

martinklepsch21:11:53

yes you can just (integrant.repl/reset)

martinklepsch21:11:06

(defun integrant-reset ()
  (interactive)
  (cider-interactive-eval "(integrant.repl/reset)"))
you can also add this to your emacs config and then you can just do M-x integrant-reset without opening the system buffer

martinklepsch21:11:34

This might be nice to document in "Running cljdoc locally"

devurandom23:11:44

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

martinklepsch23:11:44

replied on issue

martinklepsch23:11:09

let me know if you have any thoughts on this @U368JQA01

martinklepsch23:11:34

also just noticed @U368JQA01 = @U37339DBP? ๐Ÿ˜„

martinklepsch23:11:56

just edited again with a link to offline docs example

devurandom09:11:21

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.

martinklepsch09:11:39

@U368JQA01 that would require knowing how to build every project. unfortunately that can vary greatly from project to project

devurandom09:11:04

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?

martinklepsch09:11:15

yeah, there's lots of good stuff that could be done... all a question of the effort / impact ratio ๐Ÿ™‚

devurandom09:11:22

Yeah, maybe it only makes sense for projects beyond a certain exposition and size.

martinklepsch09:11:29

I think the offline bundle stuff would be a good first step, what do you think?

devurandom09:11:32

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

devurandom09:11:00

I'm wondering how to lower the entry bar to producing good documentation. The less services library authors have to setup themselves, the better.

devurandom10:11:00

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.

martinklepsch10:11:08

Right but that would require cloning the PR, which you wanted to avoid as far as I understood the workflow you imagined

devurandom10:11:42

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

devurandom10:11:50

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."

devurandom10:11:27

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).

devurandom10:11:36

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.

devurandom10:11:54

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.

martinklepsch10:11:53

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

martinklepsch10:11:15

I also think the /download + artifact route might be most feasible/easy for a first version

devurandom10:11:25

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.

martinklepsch10:11:59

I think we could probably make a script that - downloads cljdoc - runs ingest - builds offline bundle

devurandom10:11:23

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.

martinklepsch10:11:49

> 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

urzds12:11:08

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.

martinklepsch12:11:05

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%

urzds12:11:40

good point

urzds14:11:26

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

martinklepsch14:11:23

take on as in "work on" ๐Ÿ˜„

martinklepsch14:11:33

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

martinklepsch14:11:54

I can't assign you so you'll have to do that yourself I guess ๐Ÿ™‚

urzds14:11:07

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.

martinklepsch14:11:31

I also created a milestone (experimenting with that really) for previews related stuff: https://github.com/cljdoc/cljdoc/milestone/2

urzds14:11:48

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

urzds14:11:54

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?

martinklepsch14:11:51

Thereโ€™s no cljdoc jar yet but we can write scripts that download and run cljdoc

martinklepsch14:11:34

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