librelist archives

« back to archive

Idea for library documentation

Idea for library documentation

From:
Sebastian Hennebrueder
Date:
2013-01-02 @ 13:11
Hello,

while learning Clojure it is a great help to use (doc foo) in the REPL. I 
was wondering, if we couldn't add a library documentation as well.

To put it as a user story

As a user,
I want to see the README.md file packaged with the library, if I type (doc
'somePackage.someLibrary) in the REPL,
So that I can easily see a quick introduction to a library even when being
offline.

What do you think?

-- 
Best Regards / Viele Grüße

Sebastian Hennebrueder

-----
http://www.laliluna.de
Java software developer and trainer for Hibernate and Java Persistence

Re: [leiningen] Idea for library documentation

From:
Anthony Grimes
Date:
2013-01-02 @ 13:44
One problem with this is that leiningen does not control the doc macro. It
is included in Clojure itself. I am not at a computer at the moment, but I
highly doubt leiningen packages readmes in jars by default. If it were not
for that, something like this would be relatively trivial to implement in
reply, the thing that makes lein repl tick.

Sent from my iPhone

On Jan 2, 2013, at 7:12 AM, Sebastian Hennebrueder <usenet@laliluna.de>
wrote:

Hello,

while learning Clojure it is a great help to use (doc foo) in the REPL. I
was wondering, if we couldn't add a library documentation as well.

To put it as a user story

As a user,
I want to see the README.md file packaged with the library, if I type (doc
'somePackage.someLibrary) in the REPL,
So that I can easily see a quick introduction to a library even when being
offline.

What do you think?

-- 
Best Regards / Viele Grüße

Sebastian Hennebrueder

-----
http://www.laliluna.de
Java software developer and trainer for Hibernate and Java Persistence

Re: [leiningen] Idea for library documentation

From:
Phil Hagelberg
Date:
2013-01-02 @ 21:05
Sebastian Hennebrueder <usenet@laliluna.de> writes:

> while learning Clojure it is a great help to use (doc foo) in the
> REPL. I was wondering, if we couldn't add a library documentation as
> well.

I believe this is one of the goals of clojuredocs.org. You can already
use cdoc from Leiningen's repl to view user-contributed examples for
built-in Clojure functions, but I believe the long-term goal is to open
it up for third-party libraries being documented as well.

If you're interested in helping with this, I believe there's some code
already implemented for a REST API of a rewritten clojuredocs.org, but
no HTML UI for it yet, and they could use a hand with it. Try asking on
#clojure-doc or the main Clojure mailing list if you'd like to contribute.

-Phil

Re: [leiningen] Idea for library documentation

From:
Jean Niklas L'orange
Date:
2013-01-02 @ 14:51
Printing namespaces with doc is fixed in 1.5.0-RC1 after it broke in 1.3.0.
So if you're adding a docstring in the ns macro, it should automatically be
doc'able.

I am not at a computer at the moment, but I highly doubt leiningen packages
> readmes in jars by default.
>

Yeah, it's not included by default: See issue
#880<https://github.com/technomancy/leiningen/issues/880>
.

-- 
Regards,
Jean Niklas L'orange

Re: [leiningen] Idea for library documentation

From:
Sebastian Hennebrueder
Date:
2013-01-02 @ 21:31
The named issue #880 covers more or less the same idea.

IMHO, it is petter to pack the file as part of the JAR. Imagine, you setup
a project with a new library you want to look at. You need to run to get 
the train and can rely on the fact, that with the library the basic 
documentation is there as well.
It's pretty much the same approach as Ruby does.

Packaging the file is probably easy. I am considering to try to provide a 
REPL extension but will first discuss on the clojure channel.

 
-- 
Best Regards / Viele Grüße

Sebastian Hennebrueder

-----
http://www.laliluna.de
Java software developer and trainer for Hibernate and Java Persistence

Am 02.01.2013 um 15:51 schrieb Jean Niklas L'orange <jeannikl@hypirion.com>:

> #880

Re: [leiningen] Idea for library documentation

From:
John Gabriele
Date:
2013-01-02 @ 14:53
On Wed, Jan 2, 2013 at 8:11 AM, Sebastian Hennebrueder
<usenet@laliluna.de> wrote:
> Hello,
>
> while learning Clojure it is a great help to use (doc foo) in the REPL. I
> was wondering, if we couldn't add a library documentation as well.
>
> To put it as a user story
>
> As a user,
> I want to see the README.md file packaged with the library, if I type (doc
> 'somePackage.someLibrary) in the REPL,
> So that I can easily see a quick introduction to a library even when being
> offline.
>
> What do you think?

Hi, Sebastian.

My understanding is, the reason every project's project.clj should
contain a :url is so that its clojars page can display the link (thus
leading users to where the readme likely exists).

Since most projects:

  * have a project.clj with a :url,
  * are hosted at github, and
  * have a (markdown-formatted) README.md,

it seems like someone could write a lein plug-in to download and cache
README's on-demand --- and even render and serve them locally.

Heck, the plug-in could even check to see if there's a doc/docs
top-level directory in the project, and grab/render those files (if
any) as well.

---John

Re: [leiningen] Idea for library documentation

From:
Brian Marick
Date:
2013-01-02 @ 15:47
On Jan 2, 2013, at 8:53 AM, John Gabriele <jmg3000@gmail.com> wrote:

> Heck, the plug-in could even check to see if there's a doc/docs
> top-level directory in the project, and grab/render those files (if
> any) as well.

One thing I'm doing in Midje 1.5 is a `guide` macro that launches the 
appropriate page from a user's manual. For example, `(guide future-facts)`
launches "https://github.com/marick/Midje/wiki/Future-facts".

In addition to listing the guides itself with `(guide)`, doc strings also 
refer to guides. For example, `(doc midje-configuration)` talks about all 
the configuration options. It includes these lines:

  :visible-future               ; Whether future facts produce output.
                                ; Default true.
                                ; More: `(guide future-facts)`
  
  :partial-prerequisites        ; Whether the real function can be used.
                                ; Default false.
                                ; More: `(guide partial-prerequisites)`

Notice that although there's a doc string for `midje-configuration`, 
that's not a var a user will actually ever use. It's just a node in two 
trees of in-repl documentation that start at `(doc midje)` and `(doc 
midje-repl)`. 

I mention this because I think Clojure's approach of hanging doc strings 
off convenient values (vars, namespaces) is useful but doesn't go far 
enough. How often have you gone to http://clojure.org/sequences for the 
list of seq functions at the end of the page? Shouldn't that information 
be available in-repl? Wouldn't it be nice if the doc strings for `doall`, 
`dorun`, and `doseq` referred to each other to make it easier for newbies 
to learn which one does what? 

My point is that mechanism isn't as important as content, nor as important
as trails through the documentation. (In my idle dreams, I think of 
improving documentation via stigmergy, the process of building up 
efficient actions by agents laying down markers for other agents to 
follow. Think of how ants use pheromones to make paths to food, or using 
slime molds to discover efficient spanning trees.)

--------
Occasional consulting on programming technique
Contract programming in Ruby and Clojure
Latest book: /Functional Programming for the Object-Oriented Programmer/
https://leanpub.com/fp-oo