PDF/epub generation

.gitignore

@@ -0,0 +1 @@
+book.xml

0-stuff/author.adoc

@@ -1,3 +1,4 @@
+[authorblurb]
 = About the Author
 
 You can contact {author} at {email}.

0-stuff/introduction.adoc

@@ -1,3 +1,4 @@
+[preface]
 = Introduction
 
 This book is my second effort at writing down everything I know about APIs. _Build APIs You Wont Hate_ was essentially every complicated design I had to navigate when building an API for a mobile-centric startup that was basically a combination of Foursquare, Groupon, and Instragram. I had to think about naming endpoints, writing documentation for designers, shaping the response body JSON, was curious about which status codes to use, etc.

1-theory/3-api-contracts.adoc

@@ -337,7 +337,7 @@ which can be moved to their own files. Once these are split into their own
 files, an extra step can be taken to turn them into proper JSON Schema files.
 Once they are split out they can be referenced in a HTTP response header.
 
-[source]
+[source,http]
 ----
 Link: <http://example.com/schemas/hat.json#>; rel="describedby"
 ----

2-planning/0-introduction.adoc

@@ -2,7 +2,7 @@
 
 When I was younger and dumber, the planning stage for APIs was pretty much
 "think of a list of endpoints then start coding". This is wildly insufficient.
-As the <<theory-contracts,API Contracts>> chapter explained, contracts are
+As the <<1-theory/5-api-contracts#theory-contracts,API Contracts>> chapter explained, contracts are
 incredibly important throughout the life-cycle of an API.
 
 The information provided in _Part One: Theory_ is going to come in useful for

2-planning/2-mocking.adoc

@@ -27,7 +27,7 @@ very handy for quickly getting a HTTP server spitting out some JSON that you
 control:
 
 .Woah what a surprise, another NPM tool!
-[source]
+[source,bash]
 ----
 $ npm install -g json-server
 ----
@@ -49,14 +49,14 @@ Then you create a `db.json` file with some data in there:
 
 Now, get that server started via the CLI.
 
-[source]
+[source,bash]
 ----
 $ json-server --watch db.json
 ----
 
 When browsing to `http://localhost:3000/posts/1` you will see the following JSON:
 
-[source]
+[source,javascript]
 ----
 { "id": 1, "title": "json-server", "author": "typicode" }
 ----
@@ -78,14 +78,19 @@ a pain in the ass, conflicts will be rife as the file grows and different
 developers add different properties, etc. It's good for quick and dirty demos,
 but is probably not something you will want to use in anger.
 
-How about instead of manually maintaining `db.json`, a tool could be pointed at API contracts, and a mock server was automagically created?! Then it could figure out its own
-examples based on the examples/default values supplied in the contract, and if the description language has validation rules it could even apply those too!
+How about instead of manually maintaining `db.json`, a tool could be pointed at
+API contracts, and a mock server was automagically created?! Then it could
+figure out its own examples based on the examples/default values supplied in the
+contract, and if the description language has validation rules it could even
+apply those too!
 
 Thankfully loads of folks in the API ecosystem thought about this, and there is a wide selection of tooling.
 
 == Hosted Editors Love Mock Servers
 
-Most of the hosted editors covered so far have mock servers built in, and often it is either a case of enabling it, or it is already enabled and you just need to find the URL to the server instance.
+Most of the hosted editors covered so far have mock servers built in, and often
+it is either a case of enabling it, or it is already enabled and you just need
+to find the URL to the server instance.
 
 == Standard HTTP Mocking
 
@@ -105,7 +110,8 @@ http://stoplight.io/platform/prism/[Prism]
 
 https://github.com/danielgtaylor/apisprout[API Sprout]
 
-As always check https://openapi.tools/[OpenAPI.Tools] for the latest offering of mocking tools.
+As always check https://openapi.tools/[OpenAPI.Tools] for the latest offering of
+mocking tools.
 
 // TODO Can JSON Schema do a decent mock?
 // https://www.npmjs.com/package/mock-json-schema

2-planning/3-documentation.adoc

@@ -63,19 +63,22 @@ all sorts of other handy stuff.
 .Down arrows let you expand nested objects to avoid initial clutter.
 image::images/docs-redoc-data-struct.png[]
 
-ReDoc can be used as a React command or embedded in HTML, but the most common approach to use it is via the command line. Look at their documentation for instructions, but one way is to install as a node module.
+ReDoc can be used as a React command or embedded in HTML, but the most common
+approach to use it is via the command line. Look at their documentation for
+instructions, but one way is to install as a node module.
 
-[source]
+[source,javascript]
 ----
 $ npm install -g redoc-cli
 ----
 
 To see how the documentation looks locally, you can run a local web server using the ReDoc CLI tool.
 
-[source]
+[source,bash]
 ----
 $ redoc-cli serve openapi.yaml --watch
-TODO update example when ubuntu NodeJS stops cocking about
+Server started: http://127.0.0.1:8080
+👀  Watching /Users/phil/src/pokeapi for changes...
 ----
 
 This will run a local HTTP server, and you can load up in your local browser.
@@ -85,7 +88,7 @@ detected, and should show up when you refresh the browser.
 When somebody else asks for a look, you can ask the documentation generator to
 create HTML for sharing around.
 
-[source]
+[source,bash]
 ----
 $ redoc-cli bundle openapi.yaml
 ----

Brewfile

@@ -0,0 +1,2 @@
+brew 'asciidoc' # local book toolchain
+brew 'docbook-xsl' # output epub and other book formats

Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'asciidoctor'
+gem 'asciidoctor-pdf', '~> 1.5.pre'
+gem 'asciidoctor-epub3', '~> 1.5.pre'
+gem 'asciidoctor-diagram' # https://github.com/asciidoctor/asciidoctor-diagram
+gem 'coderay' # markdown

Gemfile.lock

@@ -0,0 +1,76 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    Ascii85 (1.0.3)
+    addressable (2.6.0)
+      public_suffix (>= 2.0.2, < 4.0)
+    afm (0.2.2)
+    asciidoctor (1.5.8)
+    asciidoctor-diagram (1.5.16)
+      asciidoctor (>= 1.5.0, < 3.x)
+    asciidoctor-epub3 (1.5.0.alpha.8)
+      asciidoctor (~> 1.5.0)
+      gepub (~> 0.6.9.2)
+      thread_safe (~> 0.3.6)
+    asciidoctor-pdf (1.5.0.alpha.16)
+      asciidoctor (>= 1.5.0)
+      prawn (>= 1.3.0, < 2.3.0)
+      prawn-icon (= 1.3.0)
+      prawn-svg (>= 0.21.0, < 0.28.0)
+      prawn-table (= 0.2.2)
+      prawn-templates (>= 0.0.3, <= 0.1.1)
+      safe_yaml (~> 1.0.4)
+      thread_safe (~> 0.3.6)
+      treetop (= 1.5.3)
+    coderay (1.1.2)
+    css_parser (1.7.0)
+      addressable
+    gepub (0.6.9.2)
+      nokogiri (~> 1.6.1)
+      rubyzip (>= 1.1.1)
+    hashery (2.1.2)
+    mini_portile2 (2.1.0)
+    nokogiri (1.6.8.1)
+      mini_portile2 (~> 2.1.0)
+    pdf-core (0.7.0)
+    pdf-reader (2.2.0)
+      Ascii85 (~> 1.0.0)
+      afm (~> 0.2.1)
+      hashery (~> 2.0)
+      ruby-rc4
+      ttfunk
+    polyglot (0.3.5)
+    prawn (2.2.2)
+      pdf-core (~> 0.7.0)
+      ttfunk (~> 1.5)
+    prawn-icon (1.3.0)
+      prawn (>= 1.1.0, < 3.0.0)
+    prawn-svg (0.27.1)
+      css_parser (~> 1.3)
+      prawn (>= 0.11.1, < 3)
+    prawn-table (0.2.2)
+      prawn (>= 1.3.0, < 3.0.0)
+    prawn-templates (0.1.1)
+      pdf-reader (~> 2.0)
+      prawn (~> 2.2)
+    public_suffix (3.0.3)
+    ruby-rc4 (0.1.5)
+    rubyzip (1.2.2)
+    safe_yaml (1.0.5)
+    thread_safe (0.3.6)
+    treetop (1.5.3)
+      polyglot (~> 0.3)
+    ttfunk (1.5.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  asciidoctor
+  asciidoctor-diagram
+  asciidoctor-epub3 (~> 1.5.pre)
+  asciidoctor-pdf (~> 1.5.pre)
+  coderay
+
+BUNDLED WITH
+   2.0.1

Makefile

@@ -1,4 +1,21 @@
-default: build-html
+default: build
+
+install:
+	brew bundle
+	bundle install
+
+build: build-html build-pdf build-epub
 
 build-html:
-	asciidoctor book.adoc -D generated -b html5
+	rm -rf generated/html/*
+	asciidoctor book.adoc -b html5 -D generated/html
+	mkdir -p generated/html/1-theory && cp -r 1-theory/images generated/html/1-theory/
+	mkdir -p generated/html/2-planning && cp -r 2-planning/images generated/html/2-planning/
+
+build-pdf:
+	asciidoctor-pdf book.adoc -D generated
+
+build-epub:
+	export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
+	a2x -v -fepub -dbook --no-xmllint book.adoc && mkdir -p generated/html
+	mkdir generated/epub && mv book.epub generated/epub/

book.adoc

@@ -1,28 +1,32 @@
 = Build APIs You Won't Hate
 Philip Sturgeon <phil@apisyouwonthate.com>
 :doctype: book
+:creator: Philip Sturgeon
+:front-cover-image: image:cover.jpeg[Front Cover,1050,1600]
+:keywords: API, architecture, REST, gRPC, RPC, HTTP, GraphQL, microservices, API Design
+:source-highlighter: coderay
 :toc:
-:leveloffset: +1
 
 include::0-stuff/author.adoc[]
 
 include::0-stuff/introduction.adoc[]
 
+:leveloffset: +1
+
 :sectnums:
 
+[part]
 = Part One: Theory
-
-:leveloffset: +1
+:imagesdir: 1-theory
 
 include::1-theory/2-different-paradigms.adoc[]
 
 include::1-theory/3-api-contracts.adoc[]
 
-:leveloffset: -1
-
+[part]
 = Part Two: Planning & Design
 
-:leveloffset: +1
+:imagesdir: 2-planning
 
 include::2-planning/0-introduction.adoc[]
 
@@ -32,10 +36,11 @@ include::2-planning/2-mocking.adoc[]
 
 include::2-planning/3-documentation.adoc[]
 
-:leveloffset: -1
-
+[part]
 = Part Three: Testing & Monitoring
 
+[part]
 = Part Four: Management
 
+[part]
 = Part Five: Further Theory