wikidoc

---

This is wikidoc. And by this, we mean this page itself. This page, this whole manual, even the site page you probably downloaded Craftsman from--all of these were created with wikidoc. Wikidoc is supported via the craftsman-wiki extension.

So what is wikidoc exactly?

wikidoc is a documentation tool

The wikidoc tool provides a way to create documentation in a fast, easy-to-learn manner. Instead of creating another documentation protocol, Craftsman just uses the wiki dialect of JSPWiki.

What this allows you to do is generate documentation without having to worry about the hassles of HTML (such as closing tags, getting the tags right in the first place, CSS, etc). Craftsman's wikidoc has a default template that will support most project's needs nicely. Extending or overriding the templates is as easy as adding a file to your source directory.

wikidoc uses the JSPWiki dialect

Wiki is a growing phenomenon. It solves a specific problem: how to create web pages quickly with a short learning curve. JSPWiki is a Java/JSP based implementation of the Wiki engine.

Wiki is an idea, not a standard. As such, the wiki dialect varies from engine to engine. Since craftsman uses JSPWiki, it uses the JSPWiki dialect for its wikidoc files. Refer to the JSPWiki dialect or the local copy (which may or may not be up to date).

Creating wikidoc documentation.

Create the wiki-doc directory

Create a directory called "wiki-doc" in your source directory. Underneath that directory, create the directories "manual" and "templates". Optionally, you can also create a "site" directory (which can be used to create a website via wikidoc). Your module's directory structure will look something like this:

+ yourmodule
  + src
    + wiki-doc
      + manual
      + site
      + templates

It is recommended that you "exclude" wiki-doc and its subdirs as src in Eclipse (or whatever your IDE is). This will prevent your IDE from trying to find Java source in these dirs. However, this is not required.

Create your documentation (*.wiki)

Now create a file in src/wiki-doc/manual. You can call it "index.wiki" (NOTE: all wikidoc files must end in ".wiki"). Usually, you want to use a proper Wiki name for your filename. So if you have a topic like "Foobar Configuration", create a file called "FoobarConfiguration.wiki". The index.wiki file is kind of a special case, as it will generate an "index.html" file for you that can then be used on webservers.

Type the following in your index.wiki:

!!!Manual
----
This is my module's manual
* point 1
* point 2
* point 3

[Wiki|http://c2.com/cgi/wiki?WikiWikiWebFaq] is easy.

This is a link to another [page|YourOtherPage].  This is the [OtherPage].

Generate the html

Call the following on your build:

ant wikidoc

It will generate the wikidoc documentation. You will find the completed documentation in doc/manual/index.html.

Create more wikidoc pages

When you view the index.html file, you will see that YourOtherPage has a red line under it (or something similar). This means the wikidoc engine could not find the corresponding YourOtherPage.wiki file. This represents a page that needs to be completed or is missing (perhaps you mistyped the wiki name?). To link from the index page to the YourOtherPage wikidoc, just create a file called YourOtherPage.wiki in the src/wiki-doc/manual directory. Generate the html (ant wikidoc), and you will see the red line has disappeared and you can now navigate to the YourOtherPage.

Creating the LeftMenu and LeftMenuFooter

You will notice in the default template that the left side of the page is complaining about missing files. Just create a LeftMenu.wiki amd a LeftMenuFooter.wiki in your src/wiki-doc/manual directory. These cells will then be populated with the contents of these wiki pages.

The LeftMenu and footer are required by the default template. If you don't want to have them, you can create your own template.

Adding your logo

You will notice a broken image link at the top of your pages. This is because you haven't added your logo.

Just create your logo (should be called logo.png in the PNG format) and copy it to the src/wiki-doc/templates directory. The next time you generate the HTML, the logo will be copied into place and the llink will be satisfied.

Creating your own wikidoc templates

The wikidoc process supports two templates: ViewTemplate.html and SiteTemplate.html. The ViewTemplate.html is used for all wikidoc files except for the site files (which are used to generate websites for projects). The SiteTemplate.html is used for files in the site directory. Both of these files use the commonheader.html file.

If you do not like the standard templates, download a copy of these files and change them to suit your needs.

TODO: include links to files and examples of what can be changed