[ANN] Grenada 1.0.0-rc.2

[Richard Möhn]

This project was announced three months ago as a ‘Common Clojure Source Metadata Model’. You might also have read about it in the Clojure Gazette. It is now called Grenada and can be described vaguely as a Clojure metadata build and distribution system. Features:

• for library authors: assemble and publish (API) documentation packages similar to Javadoc JARs, but containing well-defined data instead of HTML.
• for developers: provide structured information in addition to doc strings. Annotate Clojure objects that don't support doc strings with easily accessible documentation (to be implemented).
• for documentation editors: jazz up the documentation of existing Clojure libraries; assemble documentation and examples from different sources.
• for toolsmiths: build on a rigorously flexible model of metadata about things in the Clojure ecosystem
  

(Taken from the project home page.)

Notable products of the project:

• a data model (can be understood as a draft)
• lib-grenada, implementing the model and providing convenience
• the concept of Datadoc JARs – like Javadoc JARs, but instead of HTML containing EDN files with documentation and arbitrary other data
  
• a Leiningen plugin producing and deploying such JARs for your project
  

Status:

• Everything is usable, though not very convenient at times. If you've read the example of Dorothy the Documenter in the Clojure Gazette interview: what is described there works.
• The documentation is fairly extensive, though not well-organized.
• The auxiliary library Jolly can be used to convert Grimoire data to Datadoc JARs.
  
• I would be happy if you use the Leiningen plugin to deploy Datadoc JARs for your libraries to Clojars. – Some day there might be an application which displays those data in a way similar to Autodoc or Codox. – The plugin has some issues, though, so don't get wound up.

There's still plenty to do, but I'd be happy if you take a look. Code and history can be found under the Grenada organization on GitHub.

Richard

[Richard Möhn]

Apologies to those reading this as plain text. I had forgotten how horrible Google Groups' rendering is.

[Konstantin Shabanov]

JFYI, it’s looking good in plain text.

On 19 Aug 2015, at 16:22, Richard Möhn <richar...@posteo.de> wrote:

Apologies to those reading this as plain text. I had forgotten how horrible Google Groups' rendering is.

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@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+u...@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+u...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[zcaudate]

Hey Richard,

Great work on the project! I'd love to see the final generated output if you have time to do so. Also, we at Helpshift are working on a similar project here - https://github.com/helpshift/hydrox. It'll be great to get your input to see how the two libraries compare, what each one potentially solves and whether there is synergy for solving the documentation problem.

Chris.

[Richard Möhn]

Am Dienstag, 25. August 2015 18:11:25 UTC+9 schrieb zcaudate:

[…]

Great work on the project! I'd love to see the final generated output if you have time to do so. Also, we at Helpshift are working on a similar project here - https://github.com/helpshift/hydrox. It'll be great to get your input to see how the two libraries compare, what each one potentially solves and whether there is synergy for solving the documentation problem.

Chris.

Hi Chris,

you can download a Datadoc JAR from https://clojars.org/repo/org/clojars/rmoehn/clojure/1.7.0+003/clojure-1.7.0+003-datadoc.jar and have a look at its contents. It's pretty bare-bones right now.

Hydrox looks good! (As do your other libraries. – I hadn't had them on my radar at all until now.) It appears to be a cool new tack on documentation for me. A more expressive alternative to Codox, Autodoc & co. Correct me if I oversimplify. What I've developed is a universal container for data about Clojure code. You could store Hydrox data in it for distribution and digestion by other tools. After the end of the GSoC my schedule is in a state confusion, but as soon as this has abated I will have a closer look at Hydrox and also include it in my comparison (https://github.com/clj-grenada/grenada-spec#comparison).

Regarding the documentation problem (as I see it): Hydrox and Grenada could be parts of the solution. Still lacking are conventions for the structure of Clojure libraries and documentation, a unified approach to API documentation (as opposed to people putting Codox or Autodoc on github.io or private pages or nothing at all) and a dedicated search engine for Clojure libraries.

I would love to continue working on those things (and Grenada), but first I have to wait for feedback from Alex Miller, who was my GSoC mentor, and then I need to find some funding.

Richard

[Chris Zheng]

Hey Richard,

Yep, it’s exactly how you’ve described. The main emphasis is on writing documentation that can be verified through tests and so if the api changes, then the documentation can be fixed accordingly.

The grenada project looks to be very ambitious in it’s scope and yeah, it’ll be amazing to have a hoogle-like search engine for clojure.

btw… is datadoc a grenada thing or a java thing?

Chris

Hi Chris,

you can download a Datadoc JAR from https://clojars.org/repo/org/clojars/rmoehn/clojure/1.7.0+003/clojure-1.7.0+003-datadoc.jar and have a look at its contents. It's pretty bare-bones right now.

Hydrox looks good! (As do your other libraries. – I hadn't had them on my radar at all until now.) It appears to be a cool new tack on documentation for me. A more expressive alternative to Codox, Autodoc & co. Correct me if I oversimplify. What I've developed is a universal container for data about Clojure code. You could store Hydrox data in it for distribution and digestion by other tools. After the end of the GSoC my schedule is in a state confusion, but as soon as this has abated I will have a closer look at Hydrox and also include it in my comparison (https://github.com/clj-grenada/grenada-spec#comparison).

Regarding the documentation problem (as I see it): Hydrox and Grenada could be parts of the solution. Still lacking are conventions for the structure of Clojure libraries and documentation, a unified approach to API documentation (as opposed to people putting Codox or Autodoc on github.io or private pages or nothing at all) and a dedicated search engine for Clojure libraries.

I would love to continue working on those things (and Grenada), but first I have to wait for feedback from Alex Miller, who was my GSoC mentor, and then I need to find some funding.

Richard

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@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+u...@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 a topic in the Google Groups "Clojure" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/clojure/TTO5AfqXXf4/unsubscribe.
To unsubscribe from this group and all its topics, send an email to clojure+u...@googlegroups.com.

[Richard Möhn]

Am Mittwoch, 26. August 2015 14:52:31 UTC+9 schrieb zcaudate:

[…]

Yep, it’s exactly how you’ve described. The main emphasis is on writing documentation that can be verified through tests and so if the api changes, then the documentation can be fixed accordingly.

The grenada project looks to be very ambitious in it’s scope and yeah, it’ll be amazing to have a hoogle-like search engine for clojure.

btw… is datadoc a grenada thing or a java thing?

Datadoc JARs are a way of packaging and exchanging Grenada data. Purely my invention. :-P And sorry for the naming confusion; here is a clarification: https://github.com/clj-grenada/grenada-spec#names

Hmm, I thought Grenada's isn't too ambitious in its scope. Maybe I didn't make it clear. – Currently Grenada is only about the model for Clojure metadata (including documentation) and its implementations. Conventions, search engine etc. are – like Grenada – part of the way to a better ecosystem, but should be separate projects. The so-called roadmap might give you a good idea of where Grenada could be going: https://github.com/clj-grenada/grenada-spec/blob/devel/roadmap.md

Do you think Hoogle is an example for a good search engine? I just took a look. – The search results page is pretty awful. Almost as bad as Clojars search. From the functionality perspective something metacpan.org or search.cpan.org would be the minimum for me. For the UI I would keep Bret Victor's redesign of the amazon.com search in mind.

Richard

[Francesco Bellomi]

Hi Chris,

CrossClj is similar in spirit to Hoogle, although it is more focused on cross-project browsing

https://crossclj.info/

However, you cannot search by type signature, being Clojure not statically typed ;-)

Francesco

[Chris Zheng]

Hey Francesco,

crossclj is a great project. I use it a lot and it’s actually the one tool that keeps references up to date. However, it’d be great if the source code is open sourced.

Chris.

[Richard Möhn]

Am Mittwoch, 26. August 2015 11:33:13 UTC+9 schrieb Richard Möhn:

Am Dienstag, 25. August 2015 18:11:25 UTC+9 schrieb zcaudate:

[…]

Hydrox looks good! (As do your other libraries. – I hadn't had them on my radar at all until now.) It appears to be a cool new tack on documentation for me. A more expressive alternative to Codox, Autodoc & co. Correct me if I oversimplify. What I've developed is a universal container for data about Clojure code. You could store Hydrox data in it for distribution and digestion by other tools. After the end of the GSoC my schedule is in a state confusion, but as soon as this has abated I will have a closer look at Hydrox and also include it in my comparison (https://github.com/clj-grenada/grenada-spec#comparison).

[…]

I've included it now (https://github.com/clj-grenada/grenada-spec#build-on). Hydrox looks awesome and if I find the time to bring some structure into the Grenada documentation, I will almost surely use it. The problem is still that people have to host the documentation pages themselves and people are lazy and different people do different things. One solution could be to have a tool (lein-datadoc with some improvements) that automatically puts Hydrox data in Datadoc JARs and a web application that renders them. (This is my answer to the question what each one solves and whether there is synergy.)

Richard