Clojurians Log v2

Cross posting a question I asked here, as it’s relevant to the duct community too: https://clojurians.slack.com/archives/C52HVRVE1/p1602591007011000

I've been thinking about this as well. One solution could be an EDN file in the resources path. A keywords as keys and a map with "metadata". Similar to duct_hierarchy.edn, these files would be aggregated and merged together. Then you can use the metadata map for anything you want, e.g. docstrings

Not sure if this is actually a good solution though. Haven't decided to double down on the idea and create a project

:thinking_face: interesting I hadn’t really considered that option, but now you mention it, it is quite compelling. Though not sure why I didn’t think about this as we already do something similar in a different tool we built for deployment. I agree if we were to do it aggregating them like duct_hierarchy.edn would be essential. Forgetting the inputs for a minute, I was thinking there are essentially three levels of documentation requirements. One is providing a means to document common patterns for blocks of config… i.e. task/use-case oriented rather than at a component level. e.g. for us to configure one auth0 flow over another often requires choosing between several distinct patterns of config, where each block exposes several components worth of edn. Then there is at the level of the individual component. And finally at the level of individual keys within a component i.e. to encourage a single meaning or definition of a key across component configs, essentially embracing the ideas of spec etc.

@kevin.van.rooijen: Ok well I’ve solved the hardest problem in computer science and with this approach, which is naming it… It should be called keydox, kinda like codox but for documenting keys 😁

haha sounds like a pretty good name. And it's available

For the people familiar with codox, this would probably be clear what the intention is

Indeed

Anyway… I’d be happy to help work on this too as best I can… and help work up a proposal for this if that would help.

Also a nice thing would be if it's not just docstrings, but it can be any metadata. e.g. you could add a malli spec, or a describe the arguments. Using this metadata you can just build an interface around that

being open to extension is definitely a big bonus

Sure, I can create a project and brainstorm ideas. It probably won't be too complex. Just an initial interface like a doc function, to set the standard

A standard has to be made if this is actually supposed to work, if people start using :doc :docstring :doc-string :description then that would be a waste

yeah agreed, you probably want to view it like RDF, like a metadata vocabulary, but for EDN

Right

I was assuming supporting some level prose would be desirable too though. e.g. support for rendering code snippets etc Not necessarily saying it should support markdown. I think perhaps it needs to assume some hierarchy structure based on namespaces. i.e. maybe it would let you document at any namespace segment in :my.lib.some-component-ns/foo?

e.g. :my.lib {:some :docs} would add docs to the parent of :my.lib.some-component-ns

not sure what all implications of that are, but it would I think be useful.

hmm I'm not sure how I envision this hierarchy structure

Feel free to add ideas https://github.com/kwrooijen/keydox/issues/1

just thinking out loud; but will have a think and may try and work up an example

Sounds good

One other thing I was assuming it would target integrant (and be duct compatible that way) rather than duct itself.

Not sure what your thinking is there?

Another nice benefit is that you can actually document keys outside of the project owner's repo. e.g. you could create a duct-keydox repo and document all keys from the duct project. In case Weavejester doesn't want to add an EDN file to core

Yeah that is definitely a good idea

I was thinking outside of Integrant / Duct actually

It could be literally any keywords, from any project

yeah that makes a lot of sense

e.g. you could document Onyx keys

https://github.com/onyx-platform/onyx-examples/blob/0.14.x/catalog-parameters/src/catalog_parameters/core.clj

They also have quite a few. Thankfully namespaced

That being said, maybe we should only support namespaced keywords

e.g. :name could literally be anything

Obviously by specifying/documenting it as a format we’re punting on rendering. I was hoping eventually that it would be integrated with other clojure docs, e.g. codox though… i.e. my workaround was just going to be putting these docs into namespaces, and writing components in such a way that the primary components people would be interested in would be split one per namespace.

The namespace being the project name, possibly?

well integrant already requires namespaced keys at the top level… but not within a component. We probably need an equivalent of :req-un, i.e. perhaps the doc key is namespaced but the required key isn’t.

Having them namespaced in a nested map would prevent conflicts, if that's what you mean?

also not all components have maps of config… some are primitive values, others may be vectors, sets etc

sorry @kevin.van.rooijen this is super interesting to me, but I need to do some other work right now… I’ll have a think and may write up some thoughts ideas on your repo

👍

I've got a base profile that defines a partial map of configuration for a component, and then that base profile gets merged with dev profile with the same component key getting the rest of its configuration from a reference to another component, but it seems like when the merge of the two profiles happen, the configuration for the common key gets replaced rather than merged.

{:duct.core/environment :development
  
 ... 

 :some/component ; has some of the config
 #ig/ref :another/component
}

{:duct.profile/base
 {:duct.core/project-ns my-project
 
  ...
 
  :some/component ; has the rest of the config
  {:opt-1 "value"
   :opt-2 "value"}}

 :duct.profile/dev #duct/include "dev"}

Is it not possible to merge the config maps for a key where some of the config is provided by an Integrant reference and the rest is provided by a simple map?