Merge pull request #67 from alexdresko/doc-doc

Doc doc

CONTRIBUTING.MD

@@ -0,0 +1,4 @@
+CONTRIBUTING
+============
+
+To learn more about contributing to HSPI, please visit http://hspi.readthedocs.io/en/latest/how-to-contribute.html

docs/make.bat

@@ -26,7 +26,7 @@ if errorlevel 9009 (
 	exit /b 1
 )
 
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %2
 goto end
 
 :help

docs/source/change-log.rst

@@ -10,6 +10,7 @@ Contributers
 * 3/11/2017 10:27:59 AM by AD:   Switched to more of a gitflow (http://nvie.com/posts/a-successful-git-branching-model/) based branching strategy. The biggest reason for the switch is because I'm trying to make better use of the build system -- Basically, I don't want to continuously publish an updated nuget package and VSIX extension for every arbitrary change we make. Having a ``dev`` branch allows us to stage blocks of changes before merging ``dev`` into ``master``. It's the merging of ``dev`` into ``master`` that triggers the nuget & VSIX publishing, so you can see why merging directly into ``master`` often would be problematic. Maybe it's just me, but I think it's annoying with a nuget package or VS extension is being updated multiple times a day. 
 * 3/11/2017 10:28:05 AM by AD:   I closed out the "Good enough to use" milestone (https://github.com/alexdresko/HSPI/milestone/1) (because it is), and started "Definitive" https://github.com/alexdresko/HSPI/milestone/2
 * 5/24/2017 1:44:31 PM by AD:   Created a code of conduct in the documentation. 
+* 5/27/2017 by AD: Documentation documentation! Hopefully this will allow others to help with the HSPI documentation!
 
 Templates
 ^^^^^^^^^

docs/source/docs.rst

@@ -0,0 +1,48 @@
+Documentation
+#############
+
+Summary
+-------
+
+This document explains how to set up your environment to make changes to HSPI's documentation. If you're a new contributer to HSPI, be sure to read everything in :doc:`how-to-contribute`.
+
+HSPI's documentation is hosted on https://readthedocs.org/ (RTD). The documentation is written using Sphinx_, so you'll need Python_.  You'll also want gulp, and therefore Node if you want to take advantage of some of the utilities I wrote to make writing documentation for HSPI easier. 
+
+If you're starting with a completely new development environment, here are the steps I'd go through to get things set up. If you already have some of these tools, or prefer to do things differently, you're on your own. :) 
+
+Installing the software
+-----------------------
+
+#. Install Chocolatey_
+ At any point in the following steps, you may need to restart your console for the newly installed tool to become available in your console session. 
+#. Install git via `choco install git -y`
+#. Install python via `choco install python -y`
+#. Install VS Code via `choco install visualstudiocode -y`
+#. Install Nodejs via `choco install nodejs -y`
+#. Install Sphinx via `pip install sphinx`
+#. Install Sphinx autobuild via `pip install sphinx sphinx-autobuild`
+#. Install gulp via `npm install -g gulp`
+#. `cd` to the directory where you cloned HSPI from git
+#. Install the npm dependencies via `npm install`
+#. Install the RTD Sphinx template via `pip install sphinx_rtd_theme`
+#. Fire up the live preview by running `gulp watch` from the root of the repo. This will launch a web browser on http://localhost:3000/. Any changes you make to any of the rst files in HSPI will usually automatically refresh the browser, allowing you to see the changes you made as they'll appear on http://hspi.readthedocs.io. You might sometimes have to run `gulp build` to perform a full build of all RST files if it seems like the files aren't updating properly. Also, keep an eye on this console window between saves to make sure you don't have any errors in your RST syntax.  
+
+That's it. I just tested those instructions on my wife's laptop, in the car while she's in Walmart, tethered to my phone, while writing this very page. Clearly it works. 
+
+To learn more about Sphinx and restructuredText, go to http://www.sphinx-doc.org/en/stable/contents.html.  It takes a while to get used to rst, but it's much more powerful than Markdown. 
+
+To learn more about ReadTheDocs, go to http://docs.readthedocs.io/en/latest/
+
+
+
+
+
+.. _Python: https://www.python.org/
+.. _Sphinx: http://sphinx-doc.org/latest/install.html
+.. _Chocolatey: https://chocolatey.org/install
+
+Once you have Python and Sphinx installed, drop to a command line and run `pip install sphinx sphinx-autobuild` to get the Shinx build tool. 
+
+
+
+I prefer to write the documentation in VS Code simply because I like VS Code. 

docs/source/how-to-contribute.rst

@@ -1,17 +1,11 @@
 How to contribute
 =================
 
-Prerequisites
--------------
+.. toctree::
+    :maxdepth: 4
+    :caption: Contents:
 
-* Visual Studio 2017 (https://www.visualstudio.com/vs/) is required to develop against the HSPI repo. (You can install install the templates and consume the HSPI nuget package on VS 2015). The free Community edition plenty is powerful enough to do HS plugin development. 
-* (recommended) Resharper (https://www.jetbrains.com/resharper)
+    docs
+    code-of-conduct
 
-Setting up your development environment
----------------------------------------
 
-Development process
--------------------
-
-Integrations
-------------

docs/source/index.rst

@@ -3,7 +3,8 @@ Welcome to the HSPI documentation!
 ==================================
 
 Summary
-=======
+-------
+
 HSPI aims to make extending HomeSeer significantly easier by empowering developers with awesome tools and a collaborative community. 
 Learn more at https://github.com/alexdresko/HSPI 
 
@@ -21,7 +22,7 @@ Learn more at https://github.com/alexdresko/HSPI
     https://gitter.im/HSPI/Lobby
 
 Other Helpful Links
-===================
+-------------------
 
 * HomeSeer’s HS3 developer forum:
     https://forums.homeseer.com/forumdisplay.php?f=1138
@@ -40,7 +41,6 @@ Other Helpful Links
     getting-started
     features
     how-to-contribute
-    code-of-conduct
     change-log
     meta
 

gulpfile.js

@@ -17,4 +17,4 @@ gulp.task('watch', ['browser-sync'], () => {
     gulp.watch('./docs/source/**/*.rst', ['build']);
 });
 
-gulp.task('build', shell.task('docs\\make.bat html'));
+gulp.task('build', shell.task('docs\\make.bat html -a'));