Hi all, I'm the GSoC student. Sorry for tuning in rather late. What you talk about sounds all very familiar to me. Some comments below.
Am Mittwoch, 15. Juli 2015 03:40:26 UTC+9 schrieb Reid McKenzie: […] > I'm also advising the GSoC documentation representation project, which is > publicly visible [3] [4] although not yet advertised. I'll ping Richard to > keep an eye on this thread. > […] > [3] https://github.com/clj-grenada/grenada-spec > [4] https://github.com/clj-grenada/lib-grenada > <https://www.google.com/url?q=https%3A%2F%2Fgithub.com%2Fclj-grenada%2Flib-grenada&sa=D&sntz=1&usg=AFQjCNFA_a3_Kr2Gf3N68B53SrFqDzV0xQ> > Yeah, these are my repos. I'm especially proud that GitHub reports 100 % Perl for [3]. ;-) Aside from that, I'm completely reworking the model right now. If you're interested in that, have a look at the branch 'mosemo' in [3]. Feedback on that would help me most. My next step will be writing a file like AspectsImp.md for Bars. (You can also give feedback on the term 'Bar'.) The old model and code is kind of usable, though. I even released the 0.2.0 versions before I got into a crisis of mind. In dev/user.clj in [5] you can see some code that uses lib-grenada. There I'm scraping metadata from a Clojure library and writing a skeleton file to disk. Someone can come and fill in the skeleton with examples. The examples get postprocessed, merged back together with the metadata and packaged in a JAR. Doesn't have to do much with documentation, though. But if you want, you can give me feedback on the shape of the API. In the end, part of lib-grenada is something like a build tool for (documentation) data packages. Prismatic Graph works quite well for me, but maybe it feels icky to some people. On Mon, Jul 13, 2015 at 10:38 PM, Mikera <mike.r.an...@gmail.com <javascript:>> wrote: […] > This is the first I heard of this, but sounds like something that could do > with a decent amount of community discussion and feedback if we are going > to establish a good standard. > Some properties of such library metadata I'd like to see: > Below are some comments on whether what I have in mind/am working on fits with your desired properties. > 1) Works equally well for 3rd party tools as for clojure.core > It does. You can refer to anything that has Maven coordinates and attach documentation to it. So clojure.core is the same as anything else. > 2) Docs can be either separate or packaged in the library .jar > We have JARs with a classifier "datadoc" (up to change) that contain only the documentation (or whatever other) data. And of course you can ship those files with your library JAR as well. > 3) Tool independent (i.e. works equally well with lein, maven, cursive, > counterclockwise) > It's just a JAR of EDN files, so this should be fulfilled. People can also write other backends for storing data. > 4) Plans to migrate other tools / documentation formats > A cool demo would be to merge the official Clojure docs together with all of ClojureDocs, Clojure Grimoire, Thalia. The design also supports other Clojure platforms, but given the time constraints I think I have to focus on JVM Clojure with my programming. > 5) Well suited to automatic generation of documentation sites > Not sure what you mean. The Datadoc JARs could be loaded into IDEs' documentation browsers and, as Reid said, Grimoire will also support them. > 6) Well suited to git workflows / merging contributions etc. > I think we will generate the JARs from EDN files in some repo. If you put documentation for more than one thing in one EDN file, someone probably has to write a three-way merge tool, because Git's own three-way merge might garble the syntax. However, that's not too difficult. I've done it before for PO files. And it can be made to fit seemlessly with usual Git workflows. Again, sorry for not looking on the list so often. But especially if you CC me, I'm quite responsive. Richard [5] https://github.com/clj-grenada/grenada-ex > -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
