[jira] [Resolved] (GORA-106) Migrate Gora website documentation to Apache CMS

["Lewis John McGibbney (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/GORA-106?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Lewis John McGibbney resolved GORA-106.
---------------------------------------

    Resolution: Fixed
    
> 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
>            Assignee: Lewis John McGibbney
>            Priority: Minor
>             Fix For: 0.4
>
>         Attachments: GORA-106.patch
>
>
> 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.
> {quote}
> 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 :)
> AN EXCEPTION! And a backtrace! OH I LOVE THOSE!
>  BUILD FAILED
>  /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 ../forrest)
> 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.
> {quote}  
> 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.
> http://www.apache.org/dev/cms
> https://blogs.apache.org/infra/entry/the_asf_cms

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira