# Bitbucket Server Static Documentation

## Running

The best way to view this documentation is to run the maven site:

    cd docs
    mvn pre-site site:run

This will allow you to browse the site at http://localhost:8080/.

Unfortunately the static resources are not live-loaded and you may want to copy them manually.

    cd docs
    mvn yuicompressor:compress && cp -r src/site/resources/* target/site-webapp/

## Validation

Please ensure you check for broken links with the following:

    mvn -Dlinkcheck.offline=false clean linkcheck:linkcheck
    grep ">error<" target/linkcheck/linkcheck.xml

This will happen automatically on release and will fail at that point.

You must do a mvn clean before new linkcheck results are generated.

### Validating full docs locally

The validation above will probably have errors related to un-substituted `{$project.version}` strings, to do a full 
validation like Bamboo will do as part of the release process follow these steps in the `docs` directory:

    mvn clean site resources:resources # build the docs
    mkdir -p target/linkcheck 
    cp -r target/classes target/linkcheck/tmpsite # copy them to where linkcheck expects them
    mvn -Dlinkcheck.offline=false -Pcheck linkcheck:linkcheck # run the link check
    python ../etc/build/scan_linkcheck_for_errors.py target/linkcheck/linkcheck.xml # show errors in a friendly format

## Release

NOTE: To build a proper version of these docs a `mvn clean site resources:resources` must be executed. The resources
goal makes sure the filtering happens and maven properties (primarily `project.version`) are replaced accordingly.
The resulting proper docs are in `target/classes`, and _not in_ `target/site`.

These documents should be released as part of the normal procedure.
See `etc/release/copy_documentation_to_developer_a_c.sh`

This should deploy the documents to the following location:

https://developer.atlassian.com/stash/docs/$VERSION

## Bugs

1. Currently all content has to be referenced in the `site.xml` file. Ideally this would be generated in a custom build step.
   See https://jira.atlassian.com/browse/STASHDEV-3017.

## JSDocs

A note on the JSDocs side of things.

When building the site, we also generate JavaScript API documentation using JSDoc. This will pull in the included
directories/files from the JSDoc Config file and build the documentation files for them which will be output in to
the output directory specified in the config. Please do not add these generated files to source control.

During development, if you need to regenerate the JSDocs, you can run the following command in the `<stash>/docs` directory:

```
node_modules/.bin/jsdoc -c jsdoc-conf.json -t jsdoc-template -r
```

For more detailed information see the README in the `jsdoc-template` directory.