Contributing to the Groovy documentation

I like contributing to open source projects. I also love using Groovy for programming. Unfortunately, contributing to programming languages scares me because of all the grammar and parser stuff. I’m sure I could get into the internals with time, but I feel that time is better spent elsewhere. Now, one of those places is the Groovy user guide.

Groovy has been without a proper user guide for a long time now. Yes, there are various pages on the wiki with useful information, but it’s mostly unstructured. So the announcement of a full-blown user guide with language specification filled me with anticipation. And recently, the penny finally dropped and I realised this is something that I can contribute to. I know how to write Groovy, so all that’s required is a little bit of writing.


Update I’ve updated the link to the Groovy source repository, as it moved to Apache Incubator.

In order to motivate myself in this task, I have committed to working half an hour to an hour every day on the Groovy documentation. So far, I think I’ve hit 50% of that target in a period of a week, which is at least better than 0%. I’m also doing this in the hope it motivates some others to allocate some time to the Groovy docs. Every day is excessive, but an hour or two per week or month is still valuable and the more people involved, the quicker the progress. I also think it’s important for the community to take on much of this work in order to free up the developers to work on Groovy development! I’m thinking JVM startup time for Groovy scripts and command line apps 🙂

With that in mind, I thought it might be useful to give a brief overview of how to build the docs and contribute changes.

First steps

It can often be fiddly to contribute to open source projects, with lots of setup required. That’s not the case with the Groovy documentation because all you need are git and a text editor. If you’re really fussy, then use a text editor or IDE that supports Asciidoc syntax, as the Groovy user guide and language specification use Asciidoctor to build the HTML documents.

Assuming that you have the prerequisites, your next steps should be:

  1. Fork the apache/incubator-groovy repository on GitHub.
  2. Clone your forked repository.
  3. Open a terminal/command prompt and cd into the groovy-core directory.
  4. Run ./gradlew asciidocAll (or just gradlew asciidocAll on Windows).
  5. Open the file target/asciidoc/index.html in a browser.

Congratulations, you’re now looking at the very latest Groovy guides! All you need to do now is learn how to make changes and add content.

Adding and editing content

The source files for the Groovy guides are all based on Asciidoc. This is a wiki-like syntax with an unusual amount of power. If you want to contribute to these guides, you will have learn the syntax. Fortunately, the bulk of it is quite straightforward and you have plenty of existing source files to learn from (or copy and paste from in my case).

You can find the source files in the src/spec/doc directory. There are quite a few in there, so where do you start? The most important source file for getting started is src/spec/doc/index.adoc, the start of which I reproduce here:

= Groovy Language Documentation
:toclevels: 10
:numbered:

include::{projectdir}/src/spec/doc/core-introduction.adoc[]

== Groovy Language Specification

:leveloffset: 2
include::{projectdir}/src/spec/doc/core-syntax.adoc[]
include::{projectdir}/src/spec/doc/core-operators.adoc[]
include::{projectdir}/src/spec/doc/core-program-structure.adoc[]
include::{projectdir}/src/spec/doc/core-object-orientation.adoc[]
:leveloffset: 0

This shows you the overall structure of the combined language specification, tools guide and user guide. As you can see from the above extract, the guides are formed of several different Asciidoc source files and it’s important to know which one you should be editing. For example, section 1.2 (at the time of writing) on operators is sourced from the core-operators.adoc file – the second file in the first chapter (Groovy Language Specification). Inside core-operators.adoc, you will find all the sub-sections with their headings lead by ‘==’.

One important consideration for the guides is that all code samples are pulled from unit tests. This is important because it ensures that the guide never gets published with broken examples. You’ll find plenty of code sample segments in the Asciidoc source files, but they may not be obvious to you. Here’s an example from the operators section:


----
include::{projectdir}/src/spec/test/OperatorsTest.groovy[tags=operator_overload_class,indent=0]
----
<1> `Bucket` implements a special method called `plus()`

The first line marks this as a code segment. The bit between the dashed lines is something like a macro that pulls in a set of lines from an external source file, in this case the `OperatorsTest` class. The last line is a code annotation which allows you to attach bits of text to specific lines in the code.

This is only one side of the coin. You also need to mark the boundaries of the code you’re interested in. If you open up this OperatorsTest.groovy file you’ll find this method:

    void testOperatorOverloading() {
        assertScript '''
// tag::operator_overload_class[]
class Bucket {
    int size

    Bucket(int size) { this.size = size }

    Bucket plus(Bucket other) {                     // <1>
        return new Bucket(this.size + other.size)
    }
}
// end::operator_overload_class[]
// tag::operator_overload_op[]
def b1 = new Bucket(4)
def b2 = new Bucket(11)
assert (b1 + b2).size == 15                         // <1>
// end::operator_overload_op[]
'''
    }

The `tag::..` and `end::…` comments demarcate and label the blocks of code you want to pull into the documentation. If you take a quick look at the Asciidoc source again, you’ll see that the `include` macro references a tag called `operation_overload_class`. You can see the corresponding tag in the above method source.

This example also demonstrates how to add code annotations: simply add a line comment at the end containing just <n>. The resulting code sample in the HTML guide will have a numbered cueball at the end of the line of source code, with the same numbered cueball at the end of the sample followed by the text of that annotation.

All the sections of the various guides are already there, but some of them are empty and typically labelled with TBD. These are the ones that need work. But before you jump in and start working on a section, think on this: how do you know that someone else isn’t working on that section?

Process

At the time of writing, there is no formal process for contributing to the user guide and hence no mechanism to avoid conflicts. So before you start working on any part of the guides, I suggest you create a new local branch (I go for branches of the form doc-patch-01) and add your name to the headings of the sections you want to work on. As an example, let’s say I want to work on the operator overloading section of the language specification. I go into core-operators.adoc and add this:

[[Operator-Overloading]]
== Operator overloading (PeterLedbrook)

The bit I’ve added is in italics. Now I commit this change, push it to the doc-patch-nn branch in my remote repository and submit the pull request. Once the pull request is merged, I can start working on the section (be sure to rebase against groovy/groovy-core master branch first!). When I’ve finished, I commit my content changes to the same branch, remove my name from the section, push everything to my remote repo, and resubmit the pull request. Job done.

That’s all I want to cover here. The main focus has been the mechanics of contributing to the guides. I’ll leave it to the reader to learn how to use Asciidoc. I’m learning it myself, so I don’t think I’m ready to instruct anyone else.

Let me know how things go and whether I need to add any extra clarifications to the post.

4 thoughts on “Contributing to the Groovy documentation

  1. Jim

    Thank you for this Peter. Was thinkimg i might do some docs myself but did not know how to start. Have been trying to write a newAsciidocTemplateEngine so we could get groovy to render asciidoc.adoc files directly, so asciidoctor is currently my ‘new best friend’.

    will update you as i go forward
    thx
    jim

Leave a Reply

Your email address will not be published. Required fields are marked *