Documentation for Synse SDK (#167)

* initial commit for sdk docs

* more doc updates

* .

* add in tutorial for writing plugin from scratch

* docs docs docs

* update link in readme

.gitignore

@@ -20,4 +20,7 @@ coverage.txt
 # Dep vendor packages
 vendor
 
+# Documentation
+docs/_build
+
 .DS_Store

README.md

@@ -1,7 +1,9 @@
-<p align="center"><a href="https://www.vapor.io/"><img src="docs/assets/logo.png" width="360"></a></p>
+<p align="center"><a href="https://www.vapor.io/"><img src="docs/_static/logo.png" width="360"></a></p>
 <p align="center">
     <a href="https://circleci.com/gh/vapor-ware/synse-sdk"><img src="https://circleci.com/gh/vapor-ware/synse-sdk.svg?style=shield&circle-token=a35e96598e3df84da3dc58a4f0f9dcc8632bfbd3"></a>
     <a href="https://codecov.io/gh/vapor-ware/synse-sdk"><img src="https://codecov.io/gh/vapor-ware/synse-sdk/branch/master/graph/badge.svg?token=K9qxpN6AE2" /></a>
+    <a href="https://godoc.org/github.com/vapor-ware/synse-sdk/sdk"><img src="https://godoc.org/github.com/vapor-ware/synse-sdk/sdk?status.svg"></a>
+    <a href="https://goreportcard.com/report/github.com/vapor-ware/synse-sdk"><img src="https://goreportcard.com/badge/github.com/vapor-ware/synse-sdk"></a>
 
 <h1 align="center">Synse Plugin SDK</h1>
 </p>
@@ -83,7 +85,7 @@ The Synse Plugin SDK is released under the [GPL-2.0](LICENSE) license.
 [go-install]: https://golang.org/doc/install
 [releases]: https://github.com/vapor-ware/synse-sdk/releases
 [dep]: https://github.com/golang/dep
-[sdk-docs]: https://vapor-ware.github.io/synse-sdk/
+[sdk-docs]: http://synse-sdk.readthedocs.io/en/latest/
 [synse-server]: https://github.com/vapor-ware/synse-server
 [synse-cli]: https://github.com/vapor-ware/synse-cli
 [synse-emulator]: https://github.com/vapor-ware/synse-emulator-plugin

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = SynsePluginSDK
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_templates/sidebarfamily.html

@@ -0,0 +1,8 @@
+<h3>The Synse Family</h3>
+<ul>
+  <li><a href="https://github.com/vapor-ware/synse-server" title="Synse HTTP API Server">Synse Server</a></li>
+  <li><a href="https://github.com/vapor-ware/synse-cli" title="A CLI for Synse Server">Synse CLI</a></li>
+  <li><a href="https://github.com/vapor-ware/synse-graphql" title="GraphQL frontend for the Synse Server API">Synse GraphQL</a></li>
+  <li><a href="https://github.com/vapor-ware/synse-server-grpc" title="Synse internal gRPC API">Synse gRPC</a></li>
+  <li><a href="https://github.com/vapor-ware/synse-emulator-plugin" title="A Synse plugin providing emulated data">Synse Emulator Plugin</a></li>
+</ul>

docs/_templates/sidebarlogo.html

@@ -0,0 +1,9 @@
+<p class="logo">
+  <a href="{{ pathto(master_doc) }}">
+    <img class="logo" src="{{ pathto('_static/logo.png', 1) }}" />
+  </a>
+</p>
+
+<p align="center">
+  Created and maintained by <i><a href="https://www.vapor.io/">Vapor IO</a></i>.
+</p>

docs/community/contributing.rst

@@ -0,0 +1,15 @@
+.. _contributing:
+
+Contributing
+============
+
+Reporting an Issue
+------------------
+If you find a bug or experience unexpected behavior with the Synse Plugin SDK,
+feel free to `open an issue on GitHub <https://github.com/vapor-ware/synse-sdk/issues>`_
+
+Requesting a Feature
+--------------------
+If there is functionality missing from the Synse Plugin SDK that you think would
+be nice to have, please open a feature request issue on `GitHub <https://github.com/vapor-ware/synse-sdk/issues>`_.
+

docs/community/license.rst

@@ -0,0 +1,17 @@
+
+License
+=======
+
+The Synse Plugin SDK is licensed under the GPL-2.0 license.
+
+Briefly, that means that:
+
+    *You may copy, distribute and modify the software as
+    long as you track changes/dates in source files. Any modifications to or software
+    including (via compiler) GPL-licensed code must also be made available under
+    the GPL along with build & install instructions.*
+
+        -- `tldrleagal <https://tldrlegal.com/license/gnu-general-public-license-v2>`_
+
+For the full license, see the `LICENSE <https://github.com/vapor-ware/synse-sdk/blob/master/LICENSE>`_
+file in the source repo.

docs/community/plugins.rst

@@ -0,0 +1,26 @@
+.. _community_plugins:
+
+Community Plugins
+=================
+
+Contributing
+------------
+
+Below are some open sourced plugins developed by Vapor IO and the Synse
+Community. If you have developed your own Synse Plugin and would like to
+share it with the community, let us know by creating a new issue or opening
+a pull request to add it to this list.
+
+Plugins
+-------
+
+**Synse Emulator Plugin** (`GitHub <https://github.com/vapor-ware/synse-emulator-plugin>`_)
+
+A plugin that provides emulated devices with no back-end dependency. This
+plugin can be used for development, testing, and to just get familiar with
+Synse and plugins.
+
+
+------------
+
+.

docs/community/release_process.rst

@@ -0,0 +1,39 @@
+.. _release_process:
+
+Release Process
+===============
+
+The following guidelines describe the criteria for new releases. The Synse
+Plugin SDK is versioned with the format ``major.minor.micro``.
+
+
+Major Version
+-------------
+
+A major release will include breaking changes. When a new major release
+is cut, it will be versioned as ``X.0.0``. For example, if the previous
+release version was ``1.4.2``, the next version would be ``2.0.0``.
+
+Breaking changes are changes which break backwards compatibility with previous
+versions. Typically, this would mean changes to the API. Major releases may also
+include bug fixes.
+
+
+Minor Version
+-------------
+
+A minor release will not include breaking changes to the API, but may
+otherwise include additions, updates, or bug fixes. If the previous release
+version was ``1.4.2``, the next minor release would be ``1.5.0``.
+
+Minor version releases are backwards compatible with releases of the same major
+version number.
+
+
+Micro Version
+-------------
+
+A micro release will not include any breaking changes and will typically only
+include minor changes or bug fixes that were missed with the previous minor
+version release. If the previous release version was ``1.4.2``, the next micro
+release would be ``1.4.3``.

docs/conf.py

@@ -0,0 +1,171 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/stable/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Synse Plugin SDK'
+copyright = '2018, Vapor IO'
+author = 'Vapor IO'
+
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = '0.4.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+html_sidebars = {
+    'index': [
+        'sidebarlogo.html',
+        'sidebarfamily.html',
+        'localtoc.html',
+        'relations.html',
+        'sourcelink.html',
+        'searchbox.html'
+    ],
+    '**': [
+        'sidebarlogo.html',
+        'localtoc.html',
+        'relations.html',
+        'sourcelink.html',
+        'searchbox.html'
+    ]
+}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'SynsePluginSDKdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'SynsePluginSDK.tex', 'Synse Plugin SDK Documentation',
+     'Vapor IO', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'synsepluginsdk', 'Synse Plugin SDK Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'SynsePluginSDK', 'Synse Plugin SDK Documentation',
+     author, 'SynsePluginSDK', 'One line description of project.',
+     'Miscellaneous'),
+]