Clojurians Log v2

Hey Eugen 🙂 I'll chime in here since I just read this. I think you're very much right that the local doc generation experience is probably not as straightforward as with something that just generates some files via a CLI. That said I think there's a few reasons why you might still want to consider publishing to cljdoc: • You get free versioning of your docs and it is auto-published as you publish new releases to Clojars. • Docs are presented in a consistent format that end-users are familiar with (which also has search) While local preview could be easier there's also not that much to it, as in there's a cljdoc.edn file pointing to Markdown/Asciidoc files and then there's docstrings which are interpreted as Markdown also. 🙂 And in the end you won't have to deal with publishing the documentation files, maintaining infrastructure around that etc.

to me it's important to have the local flow and not depend on an external service

The choice is yours @eugen.stan, everything has its pros and cons. One thing to keep in mind is that cljdoc will attempt to build your docs regardless. If you change your mind, my offer to help with cljdoc still stands.

@eugen.stan Users will look on cljdoc anyway. Here's what they currently see for metrics-clojure: https://cljdoc.org/d/metrics-clojure/metrics-clojure/2.10.0/doc/readme Fine for the API but doesn't include any articles.

In order to have HTML docs available for metrics-clojure, you would need to generate them to the gh-pages branch (as a complete repo) so they show up as http://clj-commons.org/metrics-clojure/ and that is definitely not a simple, single CLI command.

I see this as 2 separate things: • building docs • publishing docs - which is gh-pages here

above I was refering to building docs - specifically - on my local system

let's say I have a strong opinion on local first

Users don't care about building docs. They care about reading them online. Don't optimize for your convenience.

you have a good point, but as long as I am puting the effort it should be ok for me. Maybe I am a bit selfish in this regard but if I don't like the process, chancess are I won't do it.

But… if you are willing to accept my help you would not be alone 🙂

thanks @lee, I did not refuse it - but also did not accept it yet

I am not trying to be difficult, just making sure I am ok with what I am getting into

And if you make it compatible with http://cljdoc.org once, every version will get its own docs automatically in future. With your approach, there are no versioned docs.

But you are volunteering your time so you should be comfortable with your choice.

(we're in the same boat with marginalia -- but that's much more complex because it has to have its docs in a particular format and generating them as HTML is the only option right now... but it's manual, there's no versioning, and I'm definitely not happy with that)

versioning is part of https://docs.readthedocs.io/en/stable/versions.html as well - via tags

I'll take some time and see if we can have our cake and eat it too

thanks for the help