Clojurians Log v2
integrant
Does anyone have any ideas about how to document integrant components/config?
We have a tonne of libraries that expose various ig/init-key components, and they’re used by a bunch of projects and I’d like to provide documentation for them that is well organised. Consuming projects usually want to paste some basic config in, and then tweak it to their needs.
Does anyone have a good way to do this sort of thing yet? I can imagine many ways to tackle it, from adding a custom macro for it, to just leveraging ns doc strings for this stuff, to just plonking them in README’s, to using a parallel set of md ascii docs for it.
Ideally I think it would work with codox or an equivalent thing somehow.
Ideally things would be documented at the component level, as some components have complex dependencies. Unfortunately clojure doesn’t let you document individual defmethod bodies.
Thanks for your answers Rick. I thought for quite a while about your issue and looked up some things. I did not find existing solutions in this space, as you put it. I was initally going to answer with a wall of text of intimidating proportions, but decided against it out of ... shyness. I'd be delighted to send you my thoughts on the subject if you're interested - feel free to message me privately and I'll dig the (600 words, 3500 chars) thing out.
OTOH, and to go back to what Kirill suggested, if some configurations are too complicated for the specs to be enough, maybe the effort should be to simplify them so that specs would be enough.
@zor I’d certainly be happy to read it
@zor: regarding simplifying configurations so the specs would be enough… that can get you a small way there but it’s really not enough. Firstly the configurations can’t really be simplified further. There’s an inherent complexity that is just complex. Also there’s a simple vs easy trade off; simplifying a component usually means splitting it up into more components… making a component easier to configure usually means handling more coercions etc and complecting separate components into one. Secondly the specs can tell you what valid values look like; but they can’t tell you why you want to use a component, or describe what it actually does. Also they can’t provide you with a documented library of components to browse and pick from. Finally you still can’t document specs themselves.
thought from another point - would it make sense to have all integrant specific methonds in one place (like main.clj) - and libs/components just provide constructors/create fns (integrant-less)? like
some component
(defn create-db-pool [] ...)main.clj
(defmethod integrant/init-key […]
(create-db-pool)):thinking_face: well that’s certainly not a bad idea
what about having specs for them? https://github.com/weavejester/integrant#specs
it doesnt solve all the problems, but at least provides some level of documentation
We already have specs for them but it’s not enough
some configurations are complicated
sorry then, dont have better option for you
Allow me to try taking your problem apart (to quote RH). What should the documentation state ? When is it needed ? Who reads it ?
@zor they’re all good questions. I was really hoping to canvas opinions to see if there were existing solutions in this space yet; before engaging in a design process. To give you some brief answers for context though… the who are developers wishing to reuse integrant components defined in libraries. Principally folk in my dev team, less important are people outside my organisation, though I think the same solution could serve them too. It’s needed at dev time, mainly serving a similar case to published API docs. A common job would be needing a pre configuring client to a deployed instance of one our services; where that client/service may support various authentication flows; e.g auth0 token auth or configured for the auth0 m2m flow etc… Many apps and systems of ours need this sort of thing and we have these integrant components already; but there’s no way beyond perhaps adding stuff in a README to document how to include them in your integrant system; and organise the docs in a standardised way across libraries and apps. The docs should I think allow documenting common tasks that span several components, and individual components too, perhaps finally allowing documentation of individual keys in a components opts map themselves.