Skip to content

Commit

Permalink
Pull out the forked theme actually, let's generate a separate war for…
Browse files Browse the repository at this point in the history 
… starters
  • Loading branch information
@gashcrumb
gashcrumb committed Nov 27, 2013
1 parent 4583389 commit 8d2a5f9
Show file tree
Hide file tree
Showing 34 changed files with 255 additions and 3,157 deletions.
13 changes: 4 additions & 9 deletions hawtio-web/genDocs → hawtio-api-docs/genDocs
View file
@@ -1,28 +1,23 @@
#!/bin/bash

#tsFiles=$(find . -type f -name *.ts | grep -v [.]d[.]ts | grep -v /test/ | grep -v target)

# install yuidoc using the steps mentioned here -> http://yui.github.io/yuidoc/##install
# or tl;dr just do npm install -g yuidocjs

src=src/main/webapp/app
out=target/docs
theme=../hawtio-docs/theme

config=target/classes/yuidoc.json

# Generate docs
function gen {
yuidoc -e .ts -t $theme -o $out $src
yuidoc -e .ts -c $config
}

# starts yuidoc in server mode
function server {
yuidoc -e .ts -t $theme -o $out --server $src
yuidoc -e .ts -c $config --server
}

# Just evaluates JSDoc comments
function lint {
yuidoc -e .ts -t $theme -o $out --lint $src
yuidoc -e .ts -c $config --lint
}

action='lint'
Expand Down
133 changes: 133 additions & 0 deletions hawtio-api-docs/pom.xml
View file
@@ -0,0 +1,133 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>

<parent>
<groupId>io.hawt</groupId>
<artifactId>project</artifactId>
<version>1.3-SNAPSHOT</version>
</parent>

<artifactId>hawtio-api-docs</artifactId>
<name>${project.artifactId}</name>
<description>hawtio :: hawtio-api-docs</description>
<packaging>war</packaging>

<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<webapp-dir>${project.artifactId}-${project.version}</webapp-dir>
<webapp-outdir>${basedir}/target/${webapp-dir}</webapp-outdir>
<gendocs>./genDocs</gendocs>
</properties>

<dependencies>

</dependencies>

<build>
<resources>
<resource>
<directory>src/main/resources</directory>
<filtering>true</filtering>
</resource>
</resources>

<plugins>

<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>${exec-maven-plugin-version}</version>
<executions>
<execution>
<id>generate-api-docs</id>
<phase>compile</phase>
<goals>
<goal>exec</goal>
</goals>
<configuration>
<executable>${gendocs}</executable>
<arguments>
<argument>-g</argument>
</arguments>
</configuration>
</execution>
</executions>
</plugin>

<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>2.6</version>
<executions>
<execution>
<id>copy-logo</id>
<phase>compile</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${webapp-outdir}</outputDirectory>
<resources>
<resource>
<directory>../hawtio-web/src/main/webapp/img</directory>
<includes>
<include>logo.png</include>
</includes>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<version>${war-plugin-version}</version>
<configuration>
<outputFileNameMapping>@{artifactId}@-@{baseVersion}@@{dashClassifier?}@.@{extension}@</outputFileNameMapping>
<warSourceDirectory>${webapp-outdir}</warSourceDirectory>
<packagingExcludes>
</packagingExcludes>
<failOnMissingWebXml>false</failOnMissingWebXml>
<archive>
<!--
<manifestFile>${basedir}/target/classes/META-INF/MANIFEST.MF</manifestFile>
-->
</archive>
</configuration>
</plugin>
</plugins>
</build>

<profiles>
<profile>
<id>watch</id>
<build>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>${exec-maven-plugin-version}</version>
<executions>
<execution>
<id>docs-watch</id>
<phase>package</phase>
<goals>
<goal>exec</goal>
</goals>
<configuration>
<executable>${gendocs}</executable>
<arguments>
<argument>-s</argument>
</arguments>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>

</project>
95 changes: 95 additions & 0 deletions hawtio-api-docs/readme.md
View file
@@ -0,0 +1,95 @@
# hawtio API docs war

This module builds a static website of API documentation from the hawtio source JSDoc comments. It uses [yuidoc](http://yui.github.io/yuidoc/) to generate a static website that includes generated HTML of all of the source.

To [install yuidoc](http://yui.github.io/yuidoc/) you use npm:

```
npm install -g yuidocjs
```

## Building

The war should build using `mvn clean install`

## Watching for source changes

You can run `mvn -Pwatch` to run yuidoc in a server mode. It'll start up a web server on port 3000 that you can use to view the docs, which are generated on the fly when the page is accessed. Any generation errors will be printed to the console.

## Examples

JSDoc Comments have to be [specifically formatted](http://yui.github.io/yuidoc/syntax/index.html) for yuidoc to pick them up, as it doesn't try and interpret the source, it just processes the JSDoc comments. So for example:

##### Example Module Block

```javascript
/**
* This is my awesome module
*
* @module MyModule
* @main MyModule
*/
```

Generally in hawtio a typescript module spans several files, so put the @main tag in the fooPlugin.ts file, and leave it out of the other .ts files in the module, that way yuidoc knows which file is the entry point for the plugin

##### Example Class Block

```javascript
/**
* This is the description for my class.
*
* @class MyClass
* @constructor
*/
```

##### Example Method Block

```javascript
/**
* My method description. Like other pieces of your comment blocks,
* this can span multiple lines.
*
* @method methodName
* @param {String} foo Argument 1
* @param {Object} config A config object
* @param {String} config.name The name on the config object
* @param {Function} config.callback A callback function on the config object
* @param {Boolean} [extra=false] Do extra, optional work
* @return {Boolean} Returns true on success
*/
```

For static functions that are in a module you could do:

```javascript
/**
* My awesome static function thingy
*
* @method myMethod
* @for MyModule
* @static
* @param {String} foo arg 1
* @return {any}
*/
```

##### Example Property Block

```javascript
/**
* My property description. Like other pieces of your comment blocks,
* this can span multiple lines.
*
* @property propertyName
* @type {Object}
* @default "foo"
*/
```

again if the property is in a module, add a `@for` with the name of the module so it's not stuck in some random class.




12 changes: 12 additions & 0 deletions hawtio-api-docs/src/main/resources/yuidoc.json
View file
@@ -0,0 +1,12 @@
{
"name": "hawtio",
"description": "The hawtio API documentation",
"version": "${project.version}",
"url": "http://hawt.io",
"logo": "logo.png",
"options": {
"outdir": "${webapp-outdir}",
"paths": "../hawtio-web/src/main/webapp/app"
}

}
Binary file removed hawtio-docs/theme/assets/css/external-small.png
View file
Binary file not shown.
Binary file removed hawtio-docs/theme/assets/css/logo.png
View file
Binary file not shown.

0 comments on commit 8d2a5f9

Please sign in to comment.