Valentin, et al, I'm a little late to the thread here, but I'm the author of lein-sphinx which you mentioned in your (well thought out) post so I thought I'd weigh in here.
I agree with a lot of what you wrote in your proposal, and for many projects (not all of them, but many) there is an important role for documentation that is separate from code. Maybe there needs to be a chapter length explanation of system X that your library is intending to interact with system X before the code (and docstrings) even make any sense to someone new to the codebase. You're going to put all that content in the code in doc strings? No. Maybe you put it in Markdown and let GitHub render it, but even with GH's proprietary extensions of MD, it's limited when compared to something like Sphinx and reStructured Text. So that's where something like lein-sphinx comes in, and I built that simply as a necessary evil. I'm not a big Python guy, or a fan of reStructured Text or Sphinx, but I felt there was nothing equivalent for building up real substantial docs in Clojure. I have some specific thoughts on your proposal are below: I've been thinking for a while that the Clojure community could benefit a > lot from a more sophisticated and ergonomic documentation system. > I would have said "usable", but I love your choice of "ergonomic" here to describe software. I think "usability" is a bit of an overused word that's lost some of its power. I'm going to steal this and start using "ergonomic". Thanks! I have seen some existing plugins like lein-sphinx, but I think it would be > really good to have documentation that would be written in Clojure, for the > following reasons : > > - we're all very fond of Clojure data structures and their syntax. (I > don't know about you, but I find that even HTML looks better in > Clojure<https://github.com/weavejester/hiccup>than in HTML). Plus, Clojure > programmers already know how to edit them. > > hmmm... I like that we could use Clojure syntax to describe Clojure syntax and Clojure data structures. I'm not so sure I'm so fond of Clojure syntax that I want to use it for sentences. And I don't think HTML looks better in Clojure, there's a lot of really nasty HTML out there. Nasty HTML looks nasty in Clojure too, and nice HTML looks better in HTML than in Clojure. > > - (better reason) The facts that Vars are first-class citizens and > that symbols can be referred explicitly with hardly any ceremony (macros) > are a exceptional opportunity to make smart and highly-structured > documentation very easily. > > mmk. > > - if it's in Clojure, Clojure programmers can seamlessly build *ad > hoc*documentation functionality on top of it to suit their own particular > needs. > > I like this reason. > I haven't found anything of the like yet, and if it exists, I would be > grateful if someone would redirect me to it. > It doesn't exist unless someone has built it internally and is keeping it for themselves (not likely). Fergal's suggestion of lein-midje-doc is probably the closest. > Here are *my thoughts on this :* > > 1. Clojure doc-strings, although they are quite handy as reminders and > for doc-indexation, are *too raw a content*. Even when they are done > right, they tend to be cumbersome, and it's too bad to have such concise > code drown in the middle of so much documentation. What's more, I believe > that when programmers program a function (or anything), they tend to think > more about the implementation than the (uninformed) usage, so they have > little incentive to make it right. > > I think doc strings are necessary, but not sufficient. I think there *is*a > role for documentation in the code, otherwise you end up duplicating documentation in the separate docs and docstrings, or in comments, so a Clojure documentation framework/solution probably out to be able to make use of doc strings by pulling out their content. It ought to also pull out things like :pre and :post. It ought to use the code to make writing the docs as easy and boilerplate free as possible. But again, when you need a lot of docs, tutorials, etc. putting that stuff directly in the code is a mess. > > 1. Building on 1. having a system where documentation and programs > live in separate files, in the same way as tests, would enforce a healthy > separation of concerns. Importantly, it would make life much easier on the > Version Control perspective. > > Yes. And just how tests refer back to the code they are testing. I think docs need to be able to refer back to the vars/atoms/functions/doc strings etc. of the code they are documenting. > > 1. Documentation should probably be made differently than what people > have got accustomed to by classical languages. Because you seldom find > types, and because IMHO Clojure programs are formed more by factoring out > recurring mechanisms in code than from implementing intellectual > abstractions, the relevant concepts tend not to be obvious in the code. > Since in Clojure we program with verbs, not > nouns<http://steve-yegge.blogspot.fr/2006/03/execution-in-kingdom-of-nouns.html>, > > I think *documentation is best made by example*. > > this seems to be a nod towards lein-midje-doc and a literate style, yes? > > 1. Documentation of a Var should not be a formal description of what > it is and what it does with some cryptically-named variables. *Every > bit of documentation should be a micro-tutorial*. Emphasis should be > put on usage, examples, tips, pitfalls, howtos. > > I'm not sure how a tool could ever have much impact on this. The human language in the docs will still be an opaque blob. At best it can make documenting examples and tips and pitfalls and what not first class and real easy to do. > > 1. There should be structure in the documentation, and it shouldn't be > just :see-also links - *there should be semantics* in it. For > example, some functions/macros are really meant to be nothing but > shorthands for calling other functions : that kind of relationship should > be explicitly documented. > > mmk. > > 1. Documentation should not be just information about each separate > Var in a namespace. There should be a hierarchy to make the most useful > elements of an API more obvious. Also, adding cross-vars documentation > elements such as tags and topics could make it easier to navigate and > understand. > > I like this. A lot of reference docs do end up "burying the lead" by documenting everything equally. > > 1. *Documentation in the REPL is great*, it was one of the very good > surprises when I started learning Clojure. However, a rich and > good-looking > presentation like in Javadocs would be welcome too. > > mmk. > Of course, all of the above are just vague principles. Here is *some > functionality I suggest for a start :* > > 1. Documentation content elements could be written in a Clojure DSL > emulating some kind of docbook-like markup language. > > IMHO this is more DSL heavy than Clojure heavy, if it's to be efficient and usable. It should probably only look much like Clojure when there is a reason to (providing a literal example of a data structure or an example or something) > 1. On the user side, the documentation would be accessible through a > generated web interface, a REPL interface, and maybe other formats like > Wiki. > > Wiki (end user edit-ability) seems like a really hard place to "start". Web and REPL sound good though. > > 1. Documentation could be programmed anywhere in a project by simply > referring to the relevant Vars and calling the documentation API. Ideally, > there would be a dedicated folder for documentation files, and a Leiningen > plugin to compile them and generate the HTML from them. > > Seems reasonable. > > 1. I often find myself lost because I have no idea what shape some > arguments to a function should have, such as config maps and maps > representing application-specific models. To adress this, I propose to > explicitly declare and describe *"stereotypes"* in the documentation. > Such stereotypes could be, for instance, "JDBC connection" or "Ring > middleware". From what I have seen, some good > work<https://github.com/prismatic/schema>has already been done in that > direction, but it would be good to make room > for it in documentation. > > Agreed. Very important to make Clojure's emphasis on value and data the real language that we think and work in. > > 1. Weigh the documentation contents by importance, to allow for > displaying the documentation with several levels of details. > > Again, I like this. Very nice thought. > > 1. Cross-vars, semantic documentation with *topics*, *tags*, and > *links*. *Topics* would group several API elements together to explain > a technique or concept; they could have a :prerequisite relationship > to help the reader navigate them. I imagine *tags* giving hints on > various aspects of a Var, such as :curried for a function, or :utility, > or :use-with-caution, etc. *Links* could be such things as the famous > :see-also, but could also represent more precise relationships, such > as :calls-to, :often-used-with, :similar-to, etc. > > I like it. > > 1. In addition to small, Var-specific, self-contained code samples, > there could be larger examples (e.g sample applications), and pointers > from > the documentation to specific points in these examples. > 2. There could be other types of documentation than just static > description, such as exercises, koans, quizzes, etc. > > > I would like to know what work has already been done in that direction, > and if you agree that this is useful, I am willing to help design and > implement it. > Your reactions are very welcome. > I plan to spend some time with lein-midje-doc to see how much itch it can scratch first, but assuming you do end up going forward with this I'd like to help out. Cheers, Sean -- 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.
