You will need:

First you need to obtain the source of the documentation project.

Clone the repository:

$ git clone [email protected]:jetty-project/jetty-documentation.git
      
    

You will now have a local directory with all of the jetty-documentation. Now we move on to building it.

$ cd jetty-documentation 
$ mvn install

    

While maven is running you may see a lot of files being downloaded. If you are not familiar with maven, then what you are seeing is maven setting up the execution environment for generating the documentation. This build should produce xhtml, as well as any other output formats that we are working with as time goes on. The downloads are all of the java dependencies that are required to make this while build work. After a while the downloading will stop and you'll see the execution of the docbkx-maven-plugin.

[INFO] --- docbkx-maven-plugin:2.0.13:generate-xhtml (documentation identifier) @ jetty-documentation ---
[INFO] Processing input file: jetty.xml
[INFO] Dumping to /home/jesse/src/projects/jetty/jetty-documentation/target/docbkx/generated/(gen)jetty.xml
[INFO] Applying customization parameters
[INFO] Chunking output. <?xml version="1.0" encoding="UTF-8"?>
[INFO] See /home/jesse/src/projects/jetty/jetty-documentation/target/docbkx/xhtml/jetty for generated file(s)
[INFO] Executing tasks
[INFO] Executed tasks

    

The build is finished once you see a message akin to this:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 7.014s
[INFO] Finished at: Tue Oct 25 14:15:37 CDT 2011
[INFO] Final Memory: 14M/229M
[INFO] ------------------------------------------------------------------------

    

You may now open your web browser and browse to the first page of the html output to see what you have produced! Generally you can do this with File -> Open File -> which will open a file system browsing screen, navigate to your jetty-documentation directory and then further into target/docbkx/xhtml/jetty/jetty.html which is the first page of the produced documentation.

Note: if the build is broke, feel free to notify us.

Now that you have built the documentation, you want to edit it and make some changes. We'll now have to take a bit of as step back and look at how git and github works. In the above example you have cloned directly from our canonical documentation repository. Obviously we can not allow anyone immediate access to this repository so you must make a fork of it for your own and then issue back pull requests to build up documentation karma. In english that means that you would go to the url of the documentation in github:

https://github.com/jetty-project/jetty-documentation

When your on this page you will see a little button called 'Fork' which you can click and you'll suddenly be taking back to your main page on github where you have a new repository. When you checkout this repository you are free to commit to your hearts delight all the changes you so direly wish to see in the jetty documentation. You can clone it to your local machine and build it same as above. So lets start small with a little example. Find some paragraph in the documentation that you think needs changed. Located that in the local checkout and make the change. Now we follow the process to push that change back into jetty proper. Do make sure the change works and the build isn't broken though so make sure you run maven and check the output. Then commit the change.

$ git commit -m "Tweaked the introduction to fix a horrid misspelled word." src/docbkbx/topics/introduction/topic.xml

    

This will commit the change that you made into git which means that now git knows about the change is you now want to push that change up to your repository on github.

$ git push

    

Now you'll see some output showing that your change has been migrated to up your repository on github. In fact if you navigate to that repository at the top of the files list you should see your comment there. Success, your change is now positioned for notifying us about it! If you click on the commit message itself you'll be taken to a screen that shows what files where changed in that commit. In the upper right corner is a button for 'Pull Request'. When you select this and follow the workflow we will then be notified of your contribution and will be able to apply it to our git repository upon review.

Thats it! You have successfully contributed to the documentation efforts of the Jetty project. After enough of these sorts of contributions and building up good community karma, you may be asked to join us as a commiter on the documentation.

Below is list of conventions that should be followed when developing documentation within this framework. These are not set in stone and should be updated as we learn more.

<?xml version="1.0" encoding="utf-8"?>
<!--
//  ========================================================================
//  Copyright (c) 1995-2012 Mort Bay Consulting Pty. Ltd.
//  ========================================================================
//  All rights reserved. This program and the accompanying materials
//  are made available under the terms of the Eclipse Public License v1.0
//  and Apache License v2.0 which accompanies this distribution.
//
//      The Eclipse Public License is available at
//      http://www.eclipse.org/legal/epl-v10.html
//
//      The Apache License v2.0 is available at
//      http://www.opensource.org/licenses/apache2.0.php
//
//  You may elect to redistribute this code under either of these licenses.
//  ========================================================================
-->