Merge pull request #159 from ponzu-cms/ponzu-dev

[cli] adding documentation server for local use

cmd/ponzu/main.go

@@ -26,17 +26,20 @@ import (
 )
 
 var (
-	port      int
 	httpsport int
+	port      int
+	docsport  int
 	https     bool
 	devhttps  bool
+	docs      bool
 	cli       bool
 
 	// for ponzu internal / core development
-	dev   bool
-	fork  string
 	gocmd string
-	year  = fmt.Sprintf("%d", time.Now().Year())
+	fork  string
+	dev   bool
+
+	year = fmt.Sprintf("%d", time.Now().Year())
 )
 
 var rootCmd = &cobra.Command{
@@ -55,7 +58,7 @@ The segments, separated by a comma, describe which services to start, either
 if the server should utilize TLS encryption - served over HTTPS, which is
 automatically managed using Let's Encrypt (https://letsencrypt.org)
 
-Defaults to 'run -port=8080 admin,api' (running Admin & API on port 8080, without TLS)
+Defaults to 'run --port=8080 admin,api' (running Admin & API on port 8080, without TLS)
 
 Note:
 Admin and API cannot run on separate processes unless you use a copy of the
@@ -81,6 +84,13 @@ $ ponzu run --port=8888 api`,
 			addTLS = "--dev-https"
 		}
 
+		var addDocs string
+		if docs {
+			addDocs = "--docs"
+		} else {
+			addDocs = "--docs=false"
+		}
+
 		var services string
 		if len(args) > 0 {
 			services = args[0]
@@ -95,6 +105,8 @@ $ ponzu run --port=8888 api`,
 			services,
 			fmt.Sprintf("--port=%d", port),
 			fmt.Sprintf("--https-port=%d", httpsport),
+			fmt.Sprintf("--docs-port=%d", docsport),
+			addDocs,
 			addTLS,
 		)
 		serve.Stderr = os.Stderr
@@ -137,6 +149,11 @@ var serveCmd = &cobra.Command{
 			}
 		}
 
+		// run docs server if --docs is true
+		if docs {
+			admin.Docs(docsport)
+		}
+
 		// save the https port the system is listening on
 		err := db.PutConfig("https_port", fmt.Sprintf("%d", httpsport))
 		if err != nil {
@@ -176,14 +193,16 @@ var serveCmd = &cobra.Command{
 
 func init() {
 	for _, cmd := range []*cobra.Command{runCmd, serveCmd} {
-		cmd.Flags().IntVar(&port, "port", 8080, "port for ponzu to bind its HTTP listener")
 		cmd.Flags().IntVar(&httpsport, "https-port", 443, "port for ponzu to bind its HTTPS listener")
+		cmd.Flags().IntVar(&port, "port", 8080, "port for ponzu to bind its HTTP listener")
+		cmd.Flags().IntVar(&docsport, "docs-port", 1234, "[dev environment] override the documentation server port")
+		cmd.Flags().BoolVar(&docs, "docs", false, "[dev environment] run HTTP server to view local HTML documentation")
 		cmd.Flags().BoolVar(&https, "https", false, "enable automatic TLS/SSL certificate management")
 		cmd.Flags().BoolVar(&devhttps, "dev-https", false, "[dev environment] enable automatic TLS/SSL certificate management")
 	}
 
-	RegisterCmdlineCommand(runCmd)
 	RegisterCmdlineCommand(serveCmd)
+	RegisterCmdlineCommand(runCmd)
 
 	pflags := rootCmd.PersistentFlags()
 	pflags.StringVar(&gocmd, "gocmd", "go", "custom go command if using beta or new release of Go")

docs/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2016 Boss Sauce Creative, LLC. 
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

docs/README.md

@@ -0,0 +1,26 @@
+# Ponzu CMS + Server Framerwork Docs
+
+## Contributing
+
+Documentation contributions are welcome and appreciated. If you find something 
+lacking in documentation or have submitted a PR that is being merged into master, 
+please help everyone out and write some docs! 
+
+**Note:** Docker is required to follow these instructions, but you can also use
+MkDocs natively, [see details here](http://www.mkdocs.org/#installation). Ponzu
+docs use the "Material" [theme](http://squidfunk.github.io/mkdocs-material/).
+
+
+Here is how to run a local docs server and build them for release:
+
+1. Clone this repository
+```bash
+$ git clone https://github.com/ponzu-cms/docs.git
+``` 
+2. Start the development server which will watch and auto-build the docs
+```bash
+$ docker run --rm -it -p 8000:8000 -v `pwd`:/docs squidfunk/mkdocs-material
+``` 
+3. Submit a PR with your changes. If you run the build step, please do not add it to the PR.
+
+**Thank you!**