Grenada is 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. ✈ ✈
-
This repo houses the Grenada specification. Start with reading the overview.
-
It also houses other things which I couldn't find a better place for. This, for example, ended up to be the home page of the Grenada project. The project structure will be improved in a visible future.
There are two names which might sound new to you: Grenada and Datadoc. I am worried that having two names will cause confusion, but I can't settle on one of them. ‘Grenada’ is not desirable as a classifier for JARs. ‘Datadoc’ is already used by several, although minor, entities in the software world and therefore won't do as a name for the whole creation.
So, endowing you with two new names, I will at least try to keep them unentangled, thus: Grenada is the name of the project, of the model and the data format defined in the spec, i. e. the name of most things. If you're not sure whether to call something Grenada something or Datadoc something, Grenada something is the safe bet. The library that implements the spec is called lib-grenada for that reason.
Datadoc always has to do with JAR files. datadoc is the classifier for JARs
that contain data in the Grenada format. You could also call it Datadoc data,
but there is not rule about that. The Leiningen plugin is called lein-datadoc,
because its main task is producing and deploying Datadoc JARs.
Datadoc is more about concretions: concrete data, concrete JARs. Grenada is more about abstractions: the Grenada model, the Grenada format, the Grenada spec.
JARs with Clojure code have versions and Things use these versions in their version coordinate. Datadoc JARs also have versions and they contain Things with version coordinates. However, the version of a Datadoc JAR doesn't have to be coupled to the version coordinates of the Things it contains. You may choose to relate it in some way, but by no means have to.
I promise that the versioning conundrum will get even worse with different versions of Bar types and Aspects. Proposals for solutions appreciated.
Here a list of tools, libraries etc. that are more or less closely related (in spirit) with Grenada.
These are sources of documentation whose contents could be packaged in Datadoc JARs.
-
Clojure Reference Documentation: the official Clojure documentation – often terse and with few examples.
-
Clojure Cheat Sheet: helps you find what you want in the official Clojure docs and selected external libraries.
-
ClojureDocs: attempt to patch over the official documentation's terseness with community-contributed notes, examples and see-alsos – easy to use and contribute to, but centered around JVM Clojure and not very structured.
-
Clojure Grimoire: similar to ClojureDocs, but highly structured and with support for arbitrary libraries on many Clojure platforms. Utilizes the aforementioned cheat sheet for easy navigation. Contributing is a little more tedious than in ClojureDocs. Offers libraries for programmatic access.
-
Thalia: extensions to the doc strings of core Clojure namespaces that you can load into your REPL.
-
Suchwow: assortment of stuff, which also contains some doc string extensions like Thalia.
-
cljs.info: something like emancipating ClojureScript documentation from Clojure documentation. Also allows community contributions. Quite useful.
These tools could build on the Grenada format or Datadoc JARs.
-
Codeq: imports Git history of Clojure (and potentially other) projects into Datomic, so that you can query it somewhat semantically.
-
CrossClj: pretty impressive (and confusing) site. Lets you search and browse the majority of Clojure libraries, their source code, documentation and, most of all, interrelations. It wouldn't make sense to build this entirely on top of Grenada, but Grenada could be a part of the foundation.
-
Codox: generates static HTML from doc strings in Clojure and ClojureScript code.
-
Autodoc: same purpose as Codox, but only for JVM Clojure, as far as I see. Used for creating the official Clojure API documentation.
-
Hydrox: a sensible approach to documentation. A tool that doesn't just dump HTML-ified doc strings, but that allows you to write beautifully formatted and structured documentation and even checks your code examples. Datadoc JARs could be used as a distribution format. With a bit of glue code it should be easy to attach all the Hydrox data to Things.
Things used by Grenada.
-
Clojars: hosts JARs of Clojure libraries and also Datadoc JARs.
-
lib-grimoire: library behind Clojure Grimoire (mentioned above). Supports querying, reading and writing data about concrete Clojure things in the Grimoire format. Grenada draws on the Grimoire format and lib-grimoire.
-
lein-grim: Leiningen ‘plugin’ that can be used to extract documentation data from Clojure code.
These don't have much to do with Grenada, other than that they're also about Clojure documentation.
-
Clojure Cookbook: recipes for accomplishing common tasks in Clojure.
-
clojure-doc.org: tutorials and topical guides on Clojure.
Except for a few commits in the beginning, branching and merging in all repositories under Grenada follows Driessen's model. Versions and releases in this repository are those of the specification.
The repositories grouped under https://github.com/clj-grenada are all in some way related to Grenada development.
…to Reid McKenzie (@arrdem) and Alex Miller (@puredanger) for mentoring me in this project.
- Introduce the term Datadoc.
- Try to be more clear introducing Grenada.
- Try to be more clear about versions in different places.
Copyright (c) 2015 Richard Möhn
This README and the specifiction are licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, see LICENSE.txt or visit https://creativecommons.org/licenses/by/4.0/.
The image files in the directory logo are licensed separately, but also under the Creative Commons Attribution 4.0 International License.
The Perl script in the directory logo is licensed under the MIT license, the text of which can be found at https://opensource.org/licenses/MIT.
The map of the location of Grenada is sourced directly from the Wikimedia Commons. For license information, simply click on the image.