the https://github.com/cljdoc/cljdoc/issues/206 looks hard for someone who haven't used clojars, maven or pom files, great i'll try to do it
yeah, it might indeed be a little hard, probably the hardest of the three issues I listed
good opportunity for me to learn hhhh
coincidentally @dominicm just wrote an article about publishing deps.edn
based projects as jars. https://juxt.pro/blog/posts/pack-maven.html
ah that's good, problem solved i guess
well... π I'm not really happy with all this pom.xml
fiddling that's required for this
But it is a start
oh i guess i have questions more than answers
ok so let me ask about this clj -m something.publish --project cljdoc --version 0.1.0
sure, ask away π
sure, ask away π
do you want a namespace named publish
that publishes any project with any version ?
π that's what i understood of that
that specific namespace was more of a placeholder π
I'll add another comment to the issue with more detail
hhhh i see :thumbsup:
alright hope this makes some more sense: https://github.com/cljdoc/cljdoc/issues/206#issuecomment-442145088
this work issue requires work on some more general Clojure tooling projects
It's an interesting thing to work on and learn about but it might also not be very beginner friendly if you're not familiar with Maven
nice: https://cljdoc.org/d/org.clojars.elarouss/cljdoc/0.1.0/doc/readme π
hhhh yeah i followed the tutorial
i'm just wondering if we can use this function from clojure/tools.deps.alpha
, but it doesn't feel safe
which function are you thinking of?
from namespace clojure.tools.deps.alpha.gen.pom
`(sync-pom (r/read-deps [(jio/file "/usr/local/Cellar/clojure/1.9.0.302/deps.edn") (jio/file "deps.edn")]) (jio/file "."))`
it works
yeah, I think that's what clj -Spom
does as well
the issue with that is that we need to manually update the generated pom.xml
omg i've just realized that deps.edn files don't contain : artifact, group ...
ah i'm sorry, i feel like i'm wasting your time and energy
Fwiw, that namespace might be removed in the future. I think it is internal.
@ichigo no worries this stuff can be confusing
Yay, finally managed to fix (integrant.repl/reset)
π https://github.com/cljdoc/cljdoc/commit/139a5a6c8094ef05cde24b93ef942b0882dbb22f
(entirely my fault that it didn't work in the first place)
yeah i guess so
Awesome! Does this mean I don't need to do (integrant.repl/stop) and then (integrant.repl/start)?
yes you can just (integrant.repl/reset)
(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 bufferThis might be nice to document in "Running cljdoc locally"
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.
@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
replied on issue
let me know if you have any thoughts on this @devurandom
also just noticed @devurandom = @urzds? π
just edited again with a link to offline docs example