Fork me on GitHub
#duct
<
2020-10-13
>
rickmoynihan12:10:20

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

Kevin13:10:23

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

Kevin13:10:21

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

rickmoynihan13:10:20

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

rickmoynihan13:10:10

@UG9U7TPDZ: 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 😁

Kevin14:10:14

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

Kevin14:10:50

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

rickmoynihan14:10:01

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.

Kevin14:10:44

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

rickmoynihan14:10:14

being open to extension is definitely a big bonus

Kevin14:10:49

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

Kevin14:10:49

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

rickmoynihan14:10:40

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

rickmoynihan14:10:12

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?

rickmoynihan14:10:09

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

rickmoynihan14:10:52

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

Kevin14:10:33

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

rickmoynihan14:10:59

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

Kevin14:10:12

Sounds good

rickmoynihan14:10:34

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

rickmoynihan14:10:44

Not sure what your thinking is there?

Kevin14:10:49

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

rickmoynihan14:10:07

Yeah that is definitely a good idea

Kevin14:10:13

I was thinking outside of Integrant / Duct actually

Kevin14:10:23

It could be literally any keywords, from any project

rickmoynihan14:10:41

yeah that makes a lot of sense

Kevin14:10:02

e.g. you could document Onyx keys

Kevin14:10:18

They also have quite a few. Thankfully namespaced

Kevin14:10:59

That being said, maybe we should only support namespaced keywords

Kevin14:10:15

e.g. :name could literally be anything

rickmoynihan14:10:06

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.

Kevin14:10:53

The namespace being the project name, possibly?

rickmoynihan14:10:42

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.

Kevin14:10:10

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

rickmoynihan14:10:12

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

rickmoynihan14:10:02

sorry @UG9U7TPDZ 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

Kevin08:10:02

Shared my thoughts. I think we're pretty much on the same page but have different approaches. I'm not sure if the "finding project name" is viable, but it would keep the keydox.edn file simple (instead of having to add extra context / nesting)

👀 3
rickmoynihan08:10:07

Yeah seems like we’re very close to agreement here. I’ll repond on the issue to clarify a few more points though.

👍 3
aeskilson22:10:54

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"}
When I bring a system like this up, I get the config of :some/component being equal to just that provided by the dev profile, rather than the dev and base profile merged.

aeskilson22:10:30

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?