Added docs using slate #1

cyrusaf · 2018-01-16T20:06:36Z

Added docs using slate docs. Added make commands to automatically setup/dev/build/publish docs to gh-pages. Slate requires ruby >= 2.3.1.

TODO:

docs/README

hyandell · 2018-01-17T08:23:37Z

Noting that the code of conduct should use our standard text/approach, rather than slate's. See oss-dashboard's CONTRIBUTING file ( https://github.com/amzn/oss-dashboard/ ).

hyandell · 2018-01-17T08:25:30Z

docs/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2008-2013 Concur Technologies, Inc.


This is a source header and not a license file.

Are Concur the author of Slate? ie: It's injecting its license into its output?

I believe they are. I'm new to open source -- is it ok to remove the docs/LICENSE file? Almost everything inside docs/* is cloned from the slate github repo.

spenczar

Thanks for doing this!

Please delete the .DS_Store files and the logo-old.png file.

The content lives in a separate branch?

spenczar · 2018-01-16T20:09:56Z

docs/README.md

+Features
+------------
+
+* **Clean, intuitive design** — With Slate, the description of your API is on the left side of your documentation, and all the code examples are on the right side. Inspired by [Stripe's](https://stripe.com/docs/api) and [Paypal's](https://developer.paypal.com/webapps/developer/docs/api/) API docs. Slate is responsive, so it looks great on tablets, phones, and even in print.


Let's drop Slate's marketing copy from this file.

spenczar · 2018-01-16T20:11:20Z

Makefile

@@ -30,6 +30,21 @@ setup:
 	GOPATH=$(CURDIR)/_tools go install github.com/twitchtv/retool/...
 	$(RETOOL) build

+# Make commands for twirp docs
+setup_docs:
+	echo "Ruby >= 2.3.1 must be installed"


Use @echo "Ruby >= 2.3.1 must be installed" here. Without a leading @, Make will print the line, so you'll double-echo.

spenczar · 2018-01-16T20:12:20Z

docs/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog


This is Slate's changelog? Let's remove it.

spenczar · 2018-01-16T20:12:55Z

docs/CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Contributor Covenant Code of Conduct


I think this is slate's, so we should remove it, too.

We might want one for the repo root, but let's do that separately.

spenczar · 2018-01-16T20:14:24Z

docs/README.md

+4. Initialize and start Slate. You can either do this locally, or with Vagrant:
+
+```shell
+# either run this to run locally


Instead, let's recommend the make dev_docs command.

spenczar · 2018-01-16T20:22:52Z

docs/source/includes/_installation.md

+> Install the Twirp compiler plugin `protoc-gen-twirp`:
+
+```bash
+$ go get -u code.justin.tv/common/twirp/protoc-gen-twirp


Change to github.com/twitchtv/twirp/protoc-gen-twirp

spenczar · 2018-01-16T20:23:03Z

docs/source/includes/_updating.md

+> If you are using [retool](https://github.com/twitchtv/retool), update using the following command:
+
+```bash
+$ retool upgrade code.justin.tv/common/twirp/protoc-gen-twirp v4.4.0


Change to github.com/twitchtv/twirp/protoc-gen-twirp

spenczar · 2018-01-16T20:23:11Z

docs/source/includes/_updating.md

+$ retool upgrade code.justin.tv/common/twirp/protoc-gen-twirp v4.4.0
+```
+
+Twirp releases are tagged with semantic versioning and releases are managed by Github. See the [releases](https://git-aws.internal.justin.tv/common/twirp/releases) page.


Switch to public URL

spenczar · 2018-01-16T20:23:21Z

docs/source/includes/_updating.md

+> Use `go install` to update twirp if you don't have retool:
+
+```golang
+$ cd $GOPATH/src/code.justin.tv/common/twirp


should be public path

spenczar · 2018-01-16T20:39:16Z

docs/source/includes/_updating.md

+
+```golang
+$ cd $GOPATH/src/code.justin.tv/common/twirp
+$ git checkout v4.4.0


we're on v5.0.0 with the open source release, please update this line

cyrusaf · 2018-01-17T20:59:28Z

Makefile

+	cd docs && bundle exec middleman build --clean
+
+publish_docs: build_docs
+	git add docs/build && git push origin `git subtree split --prefix docs/build`:gh-pages --force


I want to get 👀 on this command. It builds the html files, then automatically pushes them to the gh-pages branch of whichever fork/repo you are working on. Is there a better way of doing this (a way to review the outgoing changes to the docs/build folder on github before they are pushed to gh-pages)?

The docs/build folder will just hold the built HTML documents, we can still review the source, right?

It would be nice if we could push a preview, yes. I don't know that GH pages has the flexibility to allow it, though. This might be the best we'll get within github pages.

spenczar · 2018-01-25T19:27:03Z

Slate really is kind of a pain to work with. Let's follow github.com/golang/dep's lead and use http://docusaurus.io/. I like the way the docs look and I especially like how simple it is.

RMRF-263: twirp streams POC Approved-by: Kaushik Sahoo <kaushik@gnarbox.com> Approved-by: Robert Weber <robertweber95@gmail.com> Approved-by: David Manpearl <dmanpearl@pixelmonks.com> Approved-by: Ben Balaran <ben@gnarbox.com>

allow chaining multiple ClientHooks

capture call stack for panics

spenczar self-requested a review January 16, 2018 20:07

cyrusaf force-pushed the docs branch from b7ef43d to 4271a82 Compare January 16, 2018 20:07

hyandell reviewed Jan 17, 2018

View reviewed changes

spenczar suggested changes Jan 17, 2018

View reviewed changes

spenczar added documentation project meta labels Jan 17, 2018

cyrusaf force-pushed the docs branch 2 times, most recently from 8ce78a0 to a8e11ba Compare January 17, 2018 20:48

cyrusaf commented Jan 17, 2018

View reviewed changes

Vendoring slate docs

043a5c3

cyrusaf force-pushed the docs branch from a8e11ba to e8c6221 Compare January 18, 2018 01:23

cyrusaf added 2 commits January 17, 2018 17:25

Added source/build files to docs

b89d7c0

Updated Makefile to automatically setup/dev/build/publish docs

2abed80

cyrusaf force-pushed the docs branch from e8c6221 to 2abed80 Compare January 18, 2018 01:25

spenczar mentioned this pull request Jan 18, 2018

Add curl example using protobuf format to wiki #22

Closed

spenczar closed this Jan 25, 2018

marioizquierdo deleted the docs branch December 13, 2018 21:51

rynop mentioned this pull request Jun 12, 2019

v6 removal of /twirp prefix makes upgrading hard #179

Closed

spenczar pushed a commit that referenced this pull request Dec 16, 2019

Merge pull request #1 from ccmtaylor/add-twirp-client-hooks

cc9a7eb

allow chaining multiple ClientHooks

QuantumGhost added a commit to QuantumGhost/twirp that referenced this pull request Feb 10, 2022

Merge pull request twitchtv#1 from QuantumGhost/feat/panic-stack

6601e33

capture call stack for panics

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added docs using slate #1

Added docs using slate #1

cyrusaf commented Jan 16, 2018

hyandell commented Jan 17, 2018

hyandell Jan 17, 2018

cyrusaf Jan 17, 2018

spenczar left a comment

spenczar Jan 16, 2018

spenczar Jan 16, 2018

spenczar Jan 16, 2018

spenczar Jan 16, 2018

spenczar Jan 16, 2018

spenczar Jan 16, 2018

spenczar Jan 16, 2018

spenczar Jan 16, 2018

spenczar Jan 16, 2018

spenczar Jan 16, 2018

cyrusaf Jan 17, 2018 •

edited

spenczar Jan 19, 2018

spenczar commented Jan 25, 2018

		@@ -0,0 +1,13 @@
		Copyright 2008-2013 Concur Technologies, Inc.

Added docs using slate #1

Added docs using slate #1

Conversation

cyrusaf commented Jan 16, 2018

hyandell commented Jan 17, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

spenczar left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cyrusaf Jan 17, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

spenczar commented Jan 25, 2018

cyrusaf Jan 17, 2018 •

edited