From 3967b2967f05ea0b44aad8a07c021083b9a37405 Mon Sep 17 00:00:00 2001 From: Alex Dresko Date: Sat, 27 May 2017 22:36:10 -0400 Subject: [PATCH 1/2] Documentation documentation! * * `gulp build` now does a full rebuild of the docs * reorg some of the doc structure * documentation documentation! --- docs/make.bat | 2 +- docs/source/change-log.rst | 1 + docs/source/docs.rst | 48 +++++++++++++++++++++++++++++++ docs/source/how-to-contribute.rst | 16 ++++------- docs/source/index.rst | 6 ++-- gulpfile.js | 2 +- 6 files changed, 59 insertions(+), 16 deletions(-) create mode 100644 docs/source/docs.rst diff --git a/docs/make.bat b/docs/make.bat index 749725a..e24db0f 100644 --- a/docs/make.bat +++ b/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 diff --git a/docs/source/change-log.rst b/docs/source/change-log.rst index fc0668f..d5eb614 100644 --- a/docs/source/change-log.rst +++ b/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 ^^^^^^^^^ diff --git a/docs/source/docs.rst b/docs/source/docs.rst new file mode 100644 index 0000000..d542c18 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/source/how-to-contribute.rst b/docs/source/how-to-contribute.rst index b81eb04..704853c 100644 --- a/docs/source/how-to-contribute.rst +++ b/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 ------------- \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index bbf5697..0184fb5 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/gulpfile.js b/gulpfile.js index 1c7eb98..25caa9e 100644 --- a/gulpfile.js +++ b/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')); \ No newline at end of file +gulp.task('build', shell.task('docs\\make.bat html -a')); \ No newline at end of file From 23cdff53a16532a3ed5854a2a06a16dd376b752d Mon Sep 17 00:00:00 2001 From: Alex Dresko Date: Sat, 27 May 2017 22:39:28 -0400 Subject: [PATCH 2/2] Finally, a contributing.md --- CONTRIBUTING.MD | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 CONTRIBUTING.MD diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD new file mode 100644 index 0000000..bf2d5e4 --- /dev/null +++ b/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 \ No newline at end of file