Working with documentation

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

Alternatively, to browse the docs after the site is built, you can run ruby -run -ehttpd bin/Release/nsubstitute.github.com -p8000 (when the project is built in release mode).

Adding a help page

To add a new page, create a new file in the 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 build.sh TestExamples, which will run alls the tests from the project and the tests embedded within the documentation (the generated code with be in the output directory).

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.