Generate and package documentation with telesync releases. Closes h2o…

…ai/q#1082

Makefile

@@ -31,18 +31,15 @@ build-server: ## Build server for current OS/Arch
 	go build $(LDFLAGS) -o telesync cmd/telesync/main.go
 
 build-py: ## Build wheel
-	cd py && $(MAKE) build
-
-build-examples:
-	cd py && $(MAKE) examples
+	cd py && $(MAKE) release
 
 run: ## Run server
 	go run cmd/telesync/main.go -web-dir ./ui/build -debug
 
 generate: ## Generate driver bindings
 	cd tools/telegen && $(MAKE) run
 
-release: build-ui build-py build-examples ## Prepare release builds (use "VERSION=v1.2.3 make release)"
+release: build-ui build-py ## Prepare release builds (use "VERSION=v1.2.3 make release)"
 	$(MAKE) OS=linux release-os
 	$(MAKE) OS=darwin release-os
 	$(MAKE) OS=windows release-os
@@ -51,10 +48,11 @@ release-os:
 	rm -rf build/$(REL)
 	mkdir -p build/$(REL)
 	rsync -a ui/build/ build/$(REL)/www
+	rsync -a py/build/docs build/$(REL)/
+	rsync -a py/examples build/$(REL)/
 	GOOS=$(OS) GOARCH=amd64 go build $(LDFLAGS) -o build/$(REL)/telesync cmd/telesync/main.go
-	cp py/examples.tar.gz build/$(REL)/
 	cp release.txt build/$(REL)/readme.txt
-	cd build && tar -czf $(REL).tar.gz $(REL)
+	cd build && tar -czf $(REL).tar.gz  --exclude='*.state'  --exclude='__pycache__' $(REL)
 
 help: ## List all make tasks
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

README.md

@@ -8,52 +8,10 @@
 
 ## Getting Started
 
-#### Step 1: Get Telesync
+To build apps using Telesync, you need the `telesync` development server and the `telesync` pip package.
 
-[Download](https://github.com/h2oai/telesync/releases) the development server and run:
-
-```
-$ ./telesync
-```
-
-#### Step 2: Install the Python driver
-
-```
-pip install -U telesync
-```
-
-#### Step 3: Hello World!
-
-```python
-# ----- hello.py -----
-
-from telesync import site, ui
-
-# Access the web page at http://localhost:55555/demo
-page = site['/demo']
-
-# Add some content.
-page['example'] = ui.markdown_card(
-  box='1 1 2 2',
-  title='Hello World!',
-  content='And now for something completely different.',
-)
-
-# Save the page
-page.sync()
-```
-
-#### Step 4:
-
-Run your code:
-
-```
-$ python3 hello.py
-```
-
-#### Step 5:
-
-Go to http://localhost:55555/demo
+1. [Download](https://github.com/h2oai/telesync/releases) a release. The release contains everything you need, including the SDK, documentation and examples.
+2. See `readme.txt` included with your release.
 
 ## Migration Guide
 

py/Makefile

@@ -18,21 +18,20 @@ setup: ## Install dependencies
 docs: sync-examples ## Build API docs
 	./venv/bin/sphinx-build -b html docs build/docs
 
-docs-zip: docs ## Build and package docs into a zip file
-	cd docs/build/html && zip -r ../../../telesync-api-docs.zip .
-
 purge: ## Purge previous build
 	rm -rf build dist telesync.egg-info
 
 .PHONY: examples
 examples:
 	sed -i -r -e "s/telesync.+/telesync==$(VERSION)/" examples/requirements.txt
-	tar -czf examples.tar.gz --exclude='*.state' --exclude='__pycache__' examples/
 
 sync-examples:
 	rm -f docs/example*.rst
 	./venv/bin/python docs/sync_examples.py
 
+.PHONY: release
+release: build docs examples ## Prepare release artifacts
+
 clean: purge ## Clean
 	rm -rf docs/build telesync-api-docs.zip venv
 	rm -f examples.tar.gz

release.txt

@@ -12,30 +12,18 @@ Telesync Development Server
 USAGE
 
   1. Run './telesync' and point your browser to http://localhost:55555
-  2. Run your telesync Python app (python -m my_app)
+  2. Run your Telesync Python app (python -m my_app)
 
 
-REFERENCES
+NOTES
 
-  - pip package: https://pypi.org/project/telesync/
-  - Examples: https://github.com/h2oai/telesync/tree/master/py/examples
+  - For an interactive tour of Telesync, see 'examples/readme.txt'
+  - For SDK documentation, see 'docs/index.html'.
+  - For example apps and code snippets, see 'examples/'.
+  - For additional command-line options, run './telesync -help'
+  - For the pip package, see https://pypi.org/project/telesync/
 
 
-COMMAND LINE OPTIONS
+Happy Telesync'ing!
+
 
-  -access-key-id string
-        default access key ID (default "access_key_id")
-  -access-key-secret string
-        default access key secret (default "access_key_secret")
-  -compact string
-        compact AOF log
-  -init string
-        initialize site content from AOF log
-  -listen string
-        listen on this address (default ":55555")
-  -tls-cert-file string
-        path to certificate file (TLS only)
-  -tls-key-file string
-        path to private key file (TLS only)
-  -webroot string
-        directory to serve web assets from (default "./www")