Merge pull request #158 from michaeltlombardi/doc-update

Reorganize project for documentation via gitbook

.github/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing to Vester
+
+Everyone is welcome to contribute to this project.
+The goal is to add fine-grained tests that look at specific values within a vSphere environment, compare them to defined configuration value, and optionally remediate discrepancies if the user so decides.
+However, there is nothing wrong with submitting a pull request (PR) with a non-remediating test.
+This is a great starting point for those newer to coding with PowerShell!
+
+## Contribution Requirements
+
+Every test that is added to Vester needs three things:
+
+1. An update to the example [`Config.ps1`][config] file with your required configuration value(s), comments, and accepted input type.
+2. An update to the [`Config.Tests.ps1`][config.tests] file to validate that the `Config.ps1` file contains valid entries.
+3. A test file using a properly formatted `Verb-Noun` format (use `Get-Verb` for more details) placed into the Tests folder.
+
+## Your First Contribution
+
+If you're looking for your first bit of code to add, try this list:
+
+1. Identify a configuration value in your vSphere environment that isn't being inspected by Vester.
+2. Use the [Template][template] to create a test that inspects this value and try it out locally.
+3. At this point you can submit a pull request (PR) for a non-remediating test.
+If someone else wants the remediation code added, they will grab your code and write that portion.
+4. Optionally, write the remediation portion yourself to make a fully remediating test.
+
+## Contribution Process
+
+1. Create a fork of the project into your own repository.
+2. From your fork, create a new feature branch (other than master) that expresses your feature or enhancement.
+3. Make all your necessary changes in your feature branch.
+4. Create a pull request with a description on what was added or removed and details explaining the changes in lines of code.
+
+If approved, project owners will merge it.
+
+[config]:       https://github.com/WahlNetwork/Vester/blob/master/Configs/Config.ps1
+[config.tests]: https://github.com/WahlNetwork/Vester/blob/master/Configs/Config.Tests.ps1
+[template]:     https://github.com/WahlNetwork/Vester/blob/master/Templates/Update-Template.ps1

.gitignore

@@ -44,3 +44,9 @@ Thumbs.db
 +# Custom Test Config #
 +######################
 +Vester/Configs/config.json
+
+# Documentation Folders/Files #
+###############################
+compiled_docs
+public
+*.pdf

CHANGELOG.md

@@ -67,19 +67,19 @@ I learned that we need to publish releases far more often. :)
   - VDS-VlanMTU-HealthCheck
 
 ### Changed
-- #114/#115: `Invoke-Vester` is **more than twice as fast** now! We removed repeated `Get` calls within private file `VesterTemplate.Tests.ps1`. Big thanks to @Midacts/@jpsider/@jonneedham for collaborating on this.
-- #118/#119: `Config.json` files now sort their settings within each scope.
+- [#114][issue-114] / [#115][issue-115]: `Invoke-Vester` is **more than twice as fast** now! We removed repeated `Get` calls within private file `VesterTemplate.Tests.ps1`. Big thanks to @Midacts/@jpsider/@jonneedham for collaborating on this.
+- [#118][issue-118] / [#119][issue-119]: `Config.json` files now sort their settings within each scope.
 
 ### Fixed
-- #90: `Invoke-Vester -Test $TestList` should execute all tests in the array, instead of just the final one after ignoring the rest. Now they do again.
-- #99: Re-implemented `-PassThru` on `Invoke-Vester`.
-- #116/#129: The name of the active vCenter connection was not being reported properly.
-- #154: Network test VDS-MTUsize had an incorrect parameter.
+- [#90][issue-90]: `Invoke-Vester -Test $TestList` should execute all tests in the array, instead of just the final one after ignoring the rest. Now they do again.
+- [#99][issue-99]: Re-implemented `-PassThru` on `Invoke-Vester`.
+- [#116][issue-116] / [#129][issue-129]: The name of the active vCenter connection was not being reported properly.
+- [#154][issue-154]: Network test VDS-MTUsize had an incorrect parameter.
 - Cleaned up VM test files:
   - Tools-DiskWiperDisable
   - Tools-HGFS-ServerDisable
 
-### Much :heart:
+### Much ❤
 [@jeffgreenca](https://github.com/jeffgreenca) [@haberstrohr](https://github.com/haberstrohr) [@jonneedham](https://github.com/jonneedham) [@Midacts](https://github.com/Midacts) [@jpsider](https://github.com/jpsider) [@Factorization](https://github.com/Factorization)
 
 
@@ -89,3 +89,13 @@ Initial availability as a PowerShell module
 
 ## [1.0.0] - 2016-11-10 [YANKED]
 Published just to reserve the name on the PowerShell Gallery. If you have this version, please update!
+
+[issue-90]:  https://github.com/WahlNetwork/Vester/issues/90
+[issue-99]:  https://github.com/WahlNetwork/Vester/issues/99
+[issue-114]: https://github.com/WahlNetwork/Vester/issues/114
+[issue-115]: https://github.com/WahlNetwork/Vester/issues/115
+[issue-116]: https://github.com/WahlNetwork/Vester/issues/116
+[issue-118]: https://github.com/WahlNetwork/Vester/issues/118
+[issue-119]: https://github.com/WahlNetwork/Vester/issues/119
+[issue-129]: https://github.com/WahlNetwork/Vester/issues/129
+[issue-154]: https://github.com/WahlNetwork/Vester/issues/154

README.md

@@ -1,12 +1,16 @@
-Vester
-======================
+# Vester
 
 [![Documentation Status](https://readthedocs.org/projects/vester/badge/?version=latest)](http://vester.readthedocs.io/en/latest/?badge=latest)
 
-Vester is a community project that aims to provide an extremely light-weight approach to vSphere configuration management using Pester and PowerCLI. The end-state configuration for each vSphere component, such as clusters and hosts, are abstracted into a simple config file. The configuration is tested--and optionally remediated--when drift is identified. The entire project is written in PowerShell.
+Vester is a community project that aims to provide an extremely light-weight approach to vSphere configuration management using Pester and PowerCLI.
+The end-state configuration for each vSphere component, such as clusters and hosts, are abstracted into a simple config file.
+The configuration is tested -- and, optionally, remediated -- when drift is identified.
+The entire project is written in PowerShell.
 
-March 2017: To learn how to use [Vester 1.0](https://www.powershellgallery.com/packages/Vester/1.0.1), there is a [three-part blog series](http://www.brianbunke.com/blog/2017/03/07/introducing-vester/) and accompanying [video demo](https://youtu.be/6DYZR-xFt-4). (Which is really long. You've been warned.)
+March 2017: To learn how to use [Vester 1.0](https://www.powershellgallery.com/packages/Vester/1.0.1), there is a [three-part blog series](http://www.brianbunke.com/blog/2017/03/07/introducing-vester/) and accompanying [video demo](https://youtu.be/6DYZR-xFt-4).
+(Which is really long. You've been warned.)
 
-> The below documentation link is outdated. We'll remove this comment when we've finished refreshing that info.
+> The below documentation link is outdated.
+> We'll remove this comment when we've finished refreshing that info.
 
 Please visit the **[full documentation](http://vester.readthedocs.io/en/latest/)** for more details.

build.ps1

@@ -0,0 +1,35 @@
+[cmdletbinding()]
+Param (
+    [string]$ApiKey,
+    [string[]]$PowerShellModules = @("Pester","Psake","BuildHelpers","Plaster"),
+    [string[]]$PackageProviders   = @('NuGet','PowerShellGet'),
+    [string[]]$TaskList
+)
+
+# Install package providers for PowerShell Modules
+ForEach ($Provider in $PackageProviders) {
+    If (!(Get-PackageProvider $Provider -ErrorAction SilentlyContinue)) {
+        Install-PackageProvider $Provider -Force -ForceBootstrap -Scope CurrentUser
+    }
+}
+
+# Install the PowerShell Modules
+ForEach ($Module in $PowerShellModules) {
+    If (!(Get-Module -ListAvailable $Module -ErrorAction SilentlyContinue)) {
+        Install-Module $Module -Scope CurrentUser -Force -Repository PSGallery
+    }
+    Import-Module $Module
+}
+
+Push-Location $PSScriptRoot
+Write-Output "Retrieving Build Variables"
+Get-ChildItem -Path env:\bh* | Remove-Item
+Set-BuildEnvironment
+
+If ($TaskList.Count -gt 0) {
+    Write-Output "Executing Tasks: $TaskList`r`n"
+    Invoke-Psake -buildFile .\psake.ps1 -properties $PSBoundParameters -noLogo -taskList $TaskList
+} Else {
+    Write-Output "Executing Unit Tests Only`r`n"
+    Invoke-Psake -buildFile .\psake.ps1 -properties $PSBoundParameters -nologo
+}

docs/.bookignore

@@ -0,0 +1 @@
+node_modules

docs/FAQ.md

@@ -0,0 +1,6 @@
+# Frequently Asked Questions
+
+This section will contain a list of questions that have been received (and answered) by the Project Team.
+
+## 1. Is this project open source? If so, using what license?
+This project _is_ open sourced under the [Apache 2.0 license](https://github.com/WahlNetwork/Vester/blob/master/LICENSE).

docs/book.json

@@ -0,0 +1,7 @@
+{
+    "title": "Vester",
+    "description": "Easily validate and remediate your vSphere configuration",
+    "author": "Chris Wahl",
+    "language": "en",
+    "plugins": ["expandable-chapters-small"]
+}

docs/concept/readme.md

@@ -0,0 +1,8 @@
+# Concept Documentation
+The following chapters contain concept guides which explain, in detail, one or more of the following:
+
++ Why a design decision was made
++ How an internal component works and why it was used
++ When and when not to use particular features or components
++ What to do when implementing this project in the user's environment
++ Which patterns are best practices and which patterns should be avoided