Merge pull request #1 from dirkrombauts/master

Documentation for version 1.0

Author: dirkrombauts

.gitignore

@@ -1,2 +1,3 @@
 _site/
 .sass-cache/
+site/

Images/TeamCityHowTo/report_config.PNG

@@ -0,0 +1,11 @@
+# Arguments
+
+Pickles provides several arguments for you to customize how it operates.  Each arguments exact usage will depend on the runner that is being used (i.e. console, powershell, etc.).  The links below provide descriptions of each parameter and how it is used in the different runners along with information on defaults and ranges of possible values.
+
+* [Feature Directory](ArgumentsFeatureDirectory.md)
+* [Output Directory](ArgumentsOutputDirectory.md)
+* [Documentation Format](ArgumentsDocumentationFormat.md)
+* [System Under Test Name](ArgumentsSystemUnderTestName.md)
+* [System Under Test Version](ArgumentsSystemUnderTestVersion.md)
+* [Test Results Format](ArgumentsTestResultsFormat.md)
+* [Test Results File](ArgumentsTestResultsFile.md)

Images/TeamCityHowTo/required_files.png

@@ -0,0 +1,40 @@
+# Documentation Format
+
+## Explanation
+
+Allows the user to select what format the generated output will be written in.  Currently, the available options are:
+
+- HTML
+- Dhtml
+- Word (OpenXML)
+- JSON
+- Excel
+
+**Note**: The value passed to this argument is case-insensitive.  i.e. HTML = html= HtMl
+
+## Default Value
+
+html
+
+## Possible Values
+
+html, dhtml, excel, json, word
+
+## Usage
+
+### Console
+
+	Pickles.exe --documentation-format=Word
+
+	Pickles.exe -df=Word
+
+### Powershell
+
+	Pickle-Features -DocumentationFormat Word
+
+### MSBuild
+
+    <target Name="document">
+        <pickles DocumentationFormat="Word" />
+    </target>
+

Images/TeamCityHowTo/scenarios_teamcity.PNG

@@ -0,0 +1,32 @@
+# Feature Directory
+
+
+## Explanation
+
+Allows the user to tell Pickles the root directory where the feature files are located.  All files underneath this root directory will be added to the output documentation.
+
+## Default Value
+
+None as yet.
+
+## Possible Values
+
+Any valid directory path, either absolute or relative.
+
+## Usage
+
+### Console
+
+	Pickles.exe --feature-directory=C:\MyProject\Features
+
+	Pickles.exe -f=C:\MyProject\Features
+
+### Powershell
+
+	Pickle-Features -FeatureDirectory C:\MyProject\Features
+
+### MSBuild
+
+    <Target Name="document">
+        <Pickles FeatureDirectory="C:\MyProject\Features" />
+    </Target>

Images/TeamCityHowTo/test_reports.PNG

@@ -0,0 +1,32 @@
+# Output Directory
+
+## Explanation
+
+The folder where Pickles will put the generated output.
+
+## Default Value
+
+The current folder.
+
+## Possible Values
+
+Any valid directory path, either absolute or relative.
+
+## Usage
+
+### Console
+
+	Pickles.exe --output-directory=C:\GeneratedDocs
+
+	Pickles.exe -o=C:\GeneratedDocs
+
+### Powershell
+
+	Pickle-Features -OutputDirectory C:\GeneratedDocs
+
+### MSBuild
+
+    <Target Name="document">
+        <Pickles OutputDirectory="C:\GeneratedDocs" />
+    </Target>
+

docs/Arguments.md

@@ -0,0 +1,32 @@
+# System Under Test Name
+
+## Explanation
+
+This is the name of the system under test.  Since Pickles is designed to be used with any platform/language that supports Gherkin feature files we cannot rely on reading in an assembly or a jar file to retrieve metadata about the system under test.  Instead, The user can use this argument to name the system under test.
+
+## Default Value
+
+None.
+
+## Possible Values
+
+Any valid string.
+
+## Usage
+
+### Console
+
+	Pickles.exe --system-under-test-name=MyProject
+
+	Pickles.exe -sn=MyProject
+
+### Powershell
+
+	Pickle-Features -SystemUnderTestName MyProject
+
+### MSBuild
+
+    <Target Name="document">
+        <Pickles SystemUnderTestName="MyProject" />
+    </Target>
+

docs/ArgumentsDocumentationFormat.md

@@ -0,0 +1,34 @@
+# System Under Test Version
+
+## Explanation
+
+This is the version of the system under test.  Since Pickles is designed to be used with any platform/language that supports Gherkin feature files we cannot rely on reading in an assembly or a jar file to retrieve metadata about the system under test.  Instead, The user can use this argument to set a version number for the system under test.
+
+This argument is typically used in conjunction with a build script on a continuous integration server.
+
+## Default Value
+
+None.
+
+## Possible Values
+
+Any valid string.
+
+## Usage
+
+### Console
+
+	Pickles.exe --system-under-test-version=2.0.1beta
+
+	Pickles.exe -sv=2.0.1beta
+
+### Powershell
+
+	Pickle-Features -SystemUnderTestVersion 2.0.1beta
+
+### MSBuild
+
+    <Target Name="document">
+        <Pickles SystemUnderTestVersion="2.0.1beta" />
+    </Target>
+

docs/ArgumentsFeatureDirectory.md

@@ -0,0 +1,31 @@
+# Test Results File
+
+## Explanation
+
+Path to the XML results file
+
+## Default Value
+
+None.
+
+## Possible Values
+
+Any path to a valid results file in XML format.
+
+## Usage
+
+### Console
+
+	Pickles.exe --link-results-file=C:\MyProject\Reports\results.xml
+
+	Pickles.exe -lr=C:\MyProject\Reports\results.xml
+
+### Powershell
+
+	Pickle-Features -TestResultsFile C:\MyProject\Reports\results.xml
+
+### MSBuild
+
+     <Target Name="document">
+         <Pickles ResultsFile="C:\MyProject\Reports\results.xml" />
+     </Target>

docs/ArgumentsOutputDirectory.md

@@ -0,0 +1,37 @@
+# Test Results Format
+
+## Explanation
+
+The format used for the report coming out of the test run of the features.  There are many different testing frameworks supported by SpecFlow, plus all of the other gherkin style frameworks out there.  NUnit and xUnit output formats are accepted as well as output from MsTest and SpecRun.
+
+Output from MsTest.exe is published in a .trx file. VsTest.Console.exe, the new command line runner as of Visual Studio 2012, is also able to produce .trx files, but those are not compatible with Pickles due to missing elements in the .trx file.
+
+
+
+**NOTE**: Values are not case-sensitive: i.e. NUNIT = nunit = NUnit
+
+## Default Value
+
+nunit
+
+## Possible Values
+
+nunit, xunit, mstest, specrun
+
+## Usage
+
+### Console
+
+	Pickles.exe --test-results-format=xunit
+
+	Pickles.exe -trfmt=xunit
+
+### Powershell
+
+	Pickle-Features -TestResultsFormat xunit
+
+### MSBuild
+
+    <Target Name="document">
+        <Pickles ResultsFormat="xunit" />
+    </Target>

docs/ArgumentsSystemUnderTestName.md

@@ -0,0 +1,30 @@
+# Console Application
+
+
+The console application is very simple and takes two parameters: the feature directory and the output directory.  
+
+## Crawling for features
+
+
+	Pickles --feature-directory=c:\dev\my-project\my-features --output-directory=c:\my-features-output
+
+This command will recursively search the directory c:\dev\my-project\my-features for feature files and render them as HTML, following the same folder structure, to c:\my-features-output with each feature generating a corresponding .xhtml file.
+
+## Viewing Available Options
+
+
+You can also call Pickles to see the available command-line parameters and their aliases like so
+
+	Pickles --help
+
+	Pickles -h
+
+	Pickles -?
+
+## Viewing Version Information
+
+You can view what version of Pickles the console application is by typing
+
+	Pickles --version
+
+	Pickles -v

docs/ArgumentsSystemUnderTestVersion.md

@@ -0,0 +1,31 @@
+# Getting Started
+
+It's very easy to get started with Pickles.  
+
+- Pick an installation method
+- Pick the runner you want (Console, GUI, PowerShell or MSBuild)
+
+## Installing via Chocolatey
+
+- [Command Line](https://chocolatey.org/packages/pickles)
+- [GUI](https://chocolatey.org/packages/picklesui)
+
+## Installing via NuGet
+
+The following runners can be installed via NuGet:
+
+- [PowerShell](http://www.nuget.org/packages/Pickles/)
+- [Command Line](http://www.nuget.org/packages/Pickles.CommandLine/)
+- [MSBuild](http://www.nuget.org/packages/Pickles.MSBuild/)
+
+## Installing via Zip Package
+
+Pre-built runners are available in a Zip package here: https://github.com/picklesdoc/pickles/releases
+
+## Build From Source
+- Download a copy of the source code from the repository
+	- [GitHub Repo](https://github.com/picklesdoc/pickles)
+	- [Tarball](https://github.com/picklesdoc/pickles/tarball/master)
+	- [Zip](https://github.com/picklesdoc/pickles/zipball/master)
+- Run the 'build-release'.cmd file to build and package the tools.
+- Pick the runner you want (Console, NAnt or MSBuild)

docs/ArgumentsTestResultsFile.md

@@ -0,0 +1,24 @@
+# How To Contribute
+
+If you like Pickles and want to contribute by all means fork the project and send me a pull request!
+
+## Ideas
+
+
+- I'm no visual designer!  What CSS layout is provided in the rendered HTML files is cobbled together from small CSS tutorials I could find on the interwebs.  If there's a CSS designer out there willing to donate some time to help improve the theme of the rendered HTML files, or even create a set of themes that the user can choose from that would be greatly appreciated.
+
+- Additional documentation builders would be great.  I plan to add the .docx format as an output in the future and perhaps .pdf as well.  If there are other formats you would like to see the features rendered in then by all means create one and send me a pull request or add an issue on the issues page.
+
+- Tasks for other build tools would be a great addition.
+	- Rake
+	- Psake
+	- Others?
+
+- Mono support so that we can run on Linux and Mac systems.
+
+- NuGet package
+	- I guess this could use the MSBuild test runner to integrate Pickles into the build process as a post-build step that has some pre-defined parameters (output folder is bin\Debug\docs, features folder is .\Features, etc.)
+
+- Chocolatey nuget package (to install the command-line executable)
+
+- Nice installer package that installs the console app, MSBuild task, NAnt task and some example projects.