You will need:

The Jetty documentation is all written in asciidoc which is used as the origin format. The maven build uses the asciidoctor-maven-plugin to process all of the .adoc files into a single docbook file which is then used to produce the final output. We use this intermediary step in order to primarily produce chunked html which we then deploy to the Eclipse Jetty website. However we can also use this docbook output to produce pdf files, epub books or even Eclipse Help files should we so desire.

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

Clone the repository:

$ git clone https://github.com/eclipse/jetty.project.git

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

$ cd jetty.project/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 will first produce docbook xml and then through the docbkx-maven-plugin generate the chunked html output. The downloads are all of the java dependencies that are required to make this build work. After a while the downloading will stop and you should see the execution of the asciidoctor-maven-plugin followed by the docbkx-maven-plugin.

[INFO] --- asciidoctor-maven-plugin:1.5.3:process-asciidoc (output-html) @ jetty-documentation ---
[INFO] Rendered /Users/jesse/src/projects/jetty/jetty-docs/src/main/asciidoc/index.adoc
[INFO]

[INFO] Processing input file: index.xml
[INFO] Applying customization parameters
[INFO] Chunking output.
[INFO] See /Users/jesse/src/projects/jetty/jetty-docs/target/docbkx/html/index for generated file(s)

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/html/index/index.html which is the first page of the produced documentation.

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/eclipse/jetty.project

When you are on this page you will see a little button called Fork which you can click and you will be taken 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 heart’s 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 the same way as above. So let’s start small with a little example. Find some paragraph in the documentation that you think needs changed. Locate that in the local checkout and make the change. Now 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 -s -m "Tweaked the introduction to fix a horrid misspelled word." src/main/asciidoc/quickstart/introduction/topic.xml

This will commit the change in your local repository. You can then push the change up to your repository on github.

$ git push

Now you’ll see some output showing that your change has been propagated to 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 were 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 committer 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.

[[this-id-an-id]]

//  ========================================================================
//  Copyright (c) 1995-2017 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.
//  ========================================================================

Some admonition examples: