Building the Web Site

The nest-spade-war development web site is a standard maven3 site, for more details than those presented in this document take a look here. In any case, below are the basic steps to building the site with on one exception to convention in that the website pages are written in DocBook XML and then transformed in APT format before the site is generated.

To begin you will need to clone the nest-spade git repository if you have no already done so.

git clone git@bitbucket.org:berkeleylab/nest-spade.git
cd nest-spade
mvn xml:transform
mvn site-deploy

The first command create a local git repository against which you can develop any changes. The next command simply moves your working directory into the project. The mvn xml:transform command generates the "Almost Plain Text" files that is then used by the last command, which builds the site and copies it off to the appropriate web server.

Before you can send it off to the web server, you will need to set up the right credentials on your ~/.m2/settings.xml file, which means including the following, where <userid> is your user name at the URL matching the <id>.

<settings>
    ...
    <servers>
        ...
        <server>
            <id>nest-website</id>
            <username>userid</username>
        </server>
        ...
    </servers>
    ...
</settings>

Modifying the Web Site

Once you have a copy of the web site (see above) you can edit any of the site files. Most of them can be found in the src/doc/docbook tree and are written using a subset of the DocBook XML schema. To preview the site locally you can use the following commands, where localpath is a path to the directory that will contain the local version of the site.

NOTE:

Avoid using " ~ " as the start of the path, as this does not get interpreted as your home directory, but rather a directory of that name that will be created in your current working directory.

mvn xml:transform
mvn site:stage -DstagingDirectory=localpath

Once you are happy with your modifications you can commit everything back into you local respository. You do this in two steps, the first step is staging any new or modified files using the following command.

git add path(s)-to-file(s)

(Remember that you should not add the .apt files as these are generated files.)

Once everything is added you can move on the the next step, commiting all your changes into your local respository using the following command.

git commit -m "commit message"

In order for others to have access to these changes there is on last step you need to execute, namely push the changes back to the common repository with the following command.

git push origin HEAD