gora-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Lewis John McGibbney (Created) (JIRA)" <j...@apache.org>
Subject [jira] [Created] (GORA-106) Migrate Gora website documentation to Apache CMS
Date Sun, 11 Mar 2012 19:32:40 GMT
Migrate Gora website documentation to Apache CMS

                 Key: GORA-106
                 URL: https://issues.apache.org/jira/browse/GORA-106
             Project: Apache Gora
          Issue Type: Improvement
          Components: documentation, website
    Affects Versions: 0.2
            Reporter: Lewis John McGibbney
            Priority: Minor
             Fix For: 0.3

I know in the past we've discussed the pro's and con's of the website etc. However, currently
it is a bit of a pain to actually edit/update, build and commit/publish web content. This
is a pain for committers never-mind any newer Gora users who may just wish to contribute documentation
in a pain/hassle free manner. To illustrate this point I've pasted a conversation with a pro-Apache
CMS ASF guy, whom I asked to look into the Gora documentation.

So, right now, there's no README.
build.xml suggests I use ant, so I did
But no readme means the first ``ant'' will complain
about forrest missing, and I'll say:
Meh. All I wanted is fix a typo.

You have to make it easy for people to contribute,
and you're not!

If you're living in a happy java world, everyone will
have maven, so maven might be the way to go. If 277
packages is all I need, then so be it, but I'll already
have them installed.

I fired up this email when I started the forrest checkout
it's only done now, after 3:26.53.
Let's see what else breaks :)


 /home/igalic/src/asf/gora-site/build.xml:27: Execute failed: java.io.IOException: Cannot
run program   "../forrest/bin/forrest" (in directory "/home/igalic/src/asf/gora-site/author"):
java.io.IOException: error=2,   No such file or directory

I touch author, but that doesn't bring me anywhere.
Of course the error is that ant or forrest can't deal with relative paths,
so I run it again as:

 igalic@tynix ~/src/asf/gora-site (svn)-[site:1240598] % ant -Dforrest.home=$( readlink -f

And it fails again, because I didn't build forrest.
By now I wonder if there's a forrest package in Fedora, but
of course there isn't. So let's build forrest.

Which in turn fails because Fedora has some weird
JAVA_HOME pointing to an OpenJDK JRE.

Back to building gora-site.
It builds in 19s and I'm impressed, or hope I have reason to be.

I go in my browser to /home/igalic/src/asf/gora-site/author/build/site
expecting it to break horribly because it's using fixed URLs
but it works. I'm impressed. I'm also impressed by its ugly,
but that's beside the point. It works. And it only took me
30 minutes to get there.

At this stage I let out a long sigh, and thought that it was about time to open this issue,
taking the following into account.
We need to "make it easy"

* for people to contribute a small fix
* for developers to actually write docs

For the latter it should be in a form and a format they are used to, something that doesn't
break their habits. If anyone has the habit of writing stuff down in notepad then markdown
might be ideal... therefore we arrive @ APACHE CMS.


This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira


View raw message