Fork me on GitHub
#duct
<
2020-08-19
>
maxov05:08:29

Hi all - been learning duct, and it’s really cool. But I feel that the beginner resources are a bit lacking, e.g. the guide doesn’t go into much depth about how duct actually works, the duct framework README is a bit terse, the core README is outdated on pretty major concepts (it still describes modules as returning a map with :req and :fn ). There’s also no good resource I could find (aside from scattered talks/blog posts) that serves as a consolidated introduction to duct and integrant. Would there be interest in a short book/longer user guide that goes into more depth and consolidates common duct usage patterns? Or maybe there’s a resource already like this I’m missing?

lukas.rychtecky11:08:41

Hej, I wrote a small post about how to build a service with Duct. I hope it can help https://flexiana.com/2020/07/building-web-services-with-duct-1-part

👍 3
maxov16:08:57

Thank you! This is quite nice

👍 3
maxov05:08:19

For a pretty major example, I think I browsed quite a few resources and didn’t ‘get’ that the final Integrant configuration map is created by folding over all the initiated profiles and modules (and that this map is completely separate from the supplied maps in e.g. config.edn) until I actually read the source

maxov05:08:27

The duct framework README almost says this, but it says something like “the original configuration is initiated into an intermediate configuration”, which is confusing because it’s that’s not the same type of initiation that Integrant performs. Integrant initiates the configuration into a series of functions, which then act as middleware producing the final configuration

Kevin07:08:10

One guide that's commonly hidden and probably the most up to date is this file https://github.com/duct-framework/docs/blob/master/GUIDE.rst

Kevin07:08:37

It doesn't go into detail about how the module system works though

Kevin07:08:28

Also, I wrote a small guide on the Duct Base config / Profiles / Modules for my colleagues a while back. I added it to the wiki. Maybe it'll be useful to others: https://github.com/duct-framework/duct/wiki/Configuration#duct-base-profiles-and-modules

👏 3
teodorlu16:08:56

Today, it was useful for me! These are core concepts that I've struggled with. Thanks!

Kevin16:08:55

Good to hear 🙂

Kevin07:08:39

However, the duct docs can use a lot of work. It's true that everything is very scattered at the moment. And a lot of outdated. It would be nice to clean everything up and only have a single source of documentation. I don't really have the authority to do that though 🙂

☝️ 12
kelveden07:08:12

Having been using Duct for a year now, I'd concur with all of this. One area that is sorely lacking in documentation in my view is the Duct merge logic e.g. what effect profiles and the likes of ^:demote, ^:promote, ^:displace , ^:replace have - again, viewing the source helps a lot here but a more holistic view would be great. I've been meaning to create an explain-merge function for a while now. As for the module system, something that helped me understand them was, after viewing the source, realising that they're essentially just "configuration factories" (i.e. components for generating more config).

👍 3
Kevin08:08:34

Most of this is documented in meta-merge, but I agree with you. Also demote / promote isn't part of meta-merge

rickmoynihan08:08:39

also duct actually implements its own version of meta-merge

Kevin08:08:39

Another thing that I think would be extremely beneficial is key documentation. Right now if you use one of the duct-framework modules, you need to read the source to know what your options are. Since keywords don't support metadata you can't add docstrings. I was thinking of having something like an integerant_meta.edn file which holds keys + maps as values. e.g.

{:some/key {:doc "documentation for this ig/init-key",,,}}
Which would allow you to add any type of metadata that you want. It would be merged similar to the duct_hierarchy.edn file and access it like the following (:doc (ig/meta :some/key)) . However weavejester has noted that he doesn't want to solve a problem like this in integrant itself. Which is understandable. it could be a separate library but if it doesn't get accepted by weavejester as a "duct" solution, and doesn't get merged in the module projects, there won't be a point

maxov16:08:38

This would be really cool.. one observation is that modules and profiles are used in a different context from most other integrant keys, and I feel a full documentation solution would somehow handle this too. But yeah, if it’s not accepted as a primary solution then I agree there’s not much point

rickmoynihan09:08:35

I definitely want docs on keys… though it’s arguably a clojure problem. It seems likely that spec/spec2 will at some point support doc strings… though who knows when that will be. Also I’d like a standardised way to document components, essentially on the defmethod, but that’s obviously a little awkward — not sure if there’s a good solution to this.

rickmoynihan09:08:24

Totally agree on the wider issues of duct documentation. I also wonder if having the docs scattered across so many repos/places is useful. It would be useful to have some centralised docs somewhere.

maxov16:08:31

Thanks for all the comments! Seems like many agree more centralized documentation would be helpful. Then I might try to write some open chapters of a duct book/guide, with burden of maintainability on me of course. If it ends up being good enough, then maybe it could be merged into the existing documentation structure. Writing helps me learn, and I already have quite a few notes on how duct works as a starter guide 😛

🙏 4
Kevin16:08:21

The only risk is that if it doesn't get merged into the official stream, then we'll have another source of documentation

maxov18:08:22

If it doesn’t get merged, then I’d be happy to mark it as inactive and link to the existing documentation to prevent this

Kevin19:08:54

I'd just rebel

Kevin16:08:45

I don't think that should dissuade you though