Working with documentation

After installing the Prerequisites, you should be able to go to Source/Docs/ from the command line and run jekyll --server --auto, then access the existing documentation via http://localhost:4000/.

Adding a help page

To add a new page, create a new file in the Source/Docs/help/_posts with the file name yyyy-mm-dd-title.markdown. The date is only important to order the documents when listed, the precise value does not matter. The file must start with some preamble:

---
title: The title (edit this to whatever you like; but don't change the layout)
layout: post
----

The rest of the file is then in markdown.

This page will then automatically appear on the left hand side nav bar.

Code samples

To highlight and show some code, wrap it in {% examplecode csharp %} / {% endexamplecode %} tags. All code between these tags, unless they contain a class or interface declaration, will be compiled and run as tests by the build. Example classes/interfaces will be available for use by the tests when compiled. If there is other code required to get these tests to run, but you don't want to display this code, you can wrap those bits of code in {% requiredcode %} / {% endrequiredcode %} tags. These will be dumped as-is into the generated test fixture (so you can add [SetUp] methods etc).

It is really important to us that the code samples are accurate, so we have a task to generate and run the code from the docs. You can try this out by running rake check_examples (the generated code with be in the output directory). You will have to do a standard build first (just run rake), because it makes it faster to compile NSubstitute once and just recompile the documents.

The current posts, and the quickstart in the index.html at the root of the docs directory will hopefully be enough to get you started.