Add docs to repo (#188)

* First pass at adding docs

* Update docs

* Fix Manifest

* Another docs fix

* Direct URLs to JuliaInterop's repo

.gitignore

@@ -0,0 +1,2 @@
+# Vim temporary files
+*.sw?

.travis.yml

@@ -8,7 +8,18 @@ julia:
     - nightly
 env:
   matrix:
-    - FORCE_COMPILE_ZMQ=yes
     - FORCE_COMPILE_ZMQ=no
+    - FORCE_COMPILE_ZMQ=yes
 notifications:
     email: false
+jobs:
+  include:
+    - stage: "Documentation"
+      julia: 1.0
+      os: linux
+      script:
+        - julia --project=docs/ -e 'using Pkg; Pkg.instantiate();
+                                    Pkg.develop(PackageSpec(path=pwd()))'
+        - julia --project=docs/ -e 'using Pkg; Pkg.build("ZMQ")'
+        - julia --project=docs/ docs/make.jl
+      after_success: skip

README.md

@@ -1,41 +1,62 @@
-# A Julia interface to ZeroMQ
-[![Build Status](https://api.travis-ci.org/JuliaInterop/ZMQ.jl.svg)](https://travis-ci.org/JuliaInterop/ZMQ.jl)
-[![Build status](https://ci.appveyor.com/api/projects/status/u1d6dpovaptdqalh?svg=true)](https://ci.appveyor.com/project/StevenGJohnson/zmq-jl)
+# ZMQ.jl
+
+*A Julia interface to ZeroMQ*
+
+| **Documentation**                                                         | **Build Status**                                                |
+|:-------------------------------------------------------------------------:|:---------------------------------------------------------------:|
+| [![][docs-stable-img]][docs-stable-url] [![][docs-dev-img]][docs-dev-url] | [![][travis-img]][travis-url] [![][appveyor-img]][appveyor-url] |
 
 **ZMQ.jl** is a [Julia](http://julialang.org) interface to [ZeroMQ, The Intelligent Transport Layer](http://zeromq.org).
 
 ## Installation
+
+The package can be installed with the Julia package manager.
+From the Julia REPL, type `]` to enter the Pkg REPL mode and run:
+
+```
+pkg> add ZMQ
+```
+
+Or, equivalently, via the `Pkg` API:
+
 ```julia
-Pkg.add("ZMQ")
+julia> import Pkg; Pkg.add("ZMQ")
 ```
 
 (This installs its own copy of the ZMQ libraries from the [ZMQBuilder](https://github.com/JuliaInterop/ZMQBuilder) repository.)
 
-## Usage
+## Documentation
 
-```julia
-using ZMQ
+- [**STABLE**][docs-stable-url] — **documentation of the most recently tagged version.**
+- [**DEVEL**][docs-dev-url] — *documentation of the in-development version.*
 
-s1=Socket(REP)
-s2=Socket(REQ)
+## Troubleshooting
 
-bind(s1, "tcp://*:5555")
-connect(s2, "tcp://localhost:5555")
+If you are using Windows and get an error `Provider PackageManager failed to satisfy dependency zmq`, you may need to restart Julia and run `Pkg.build("ZMQ")` again. See [issue #69](https://github.com/JuliaLang/ZMQ.jl/issues/69) for more details.
 
-send(s2, "test request")
-msg = recv(s1, String)
-send(s1, "test response")
-close(s1)
-close(s2)
-```
+## Questions and Contributions
 
-The `send(socket, x)` and `recv(socket, SomeType)` functions make an extra copy of the data when converting
-between ZMQ and Julia.   Alternatively, for large data sets (e.g. very large arrays or long strings), it can
-be preferable to share data, with `send(socket, Message(x))` and `msg = recv(Message)`, where the `msg::Message`
-object acts like an array of bytes; this involves some overhead so it may not be optimal for short messages.
+Usage questions can be posted on the [Julia Discourse forum][discourse-tag-url] under the `zmq` tag, in the #zmq channel of the [Julia Slack](https://julialang.org/community/) and/or in the [JuliaDocs Gitter chat room][gitter-url].
 
-(Help in writing more detailed documentation would be welcome!)
+Contributions are very welcome, as are feature requests and suggestions. Please open an [issue][issues-url] if you encounter any problems. The [contributing page][contrib-url] has a few guidelines that should be followed when opening pull requests and contributing code.
 
-## Troubleshooting
+[contrib-url]: https://juliadocs.github.io/Documenter.jl/latest/man/contributing/
+[discourse-tag-url]: https://discourse.julialang.org/tags/documenter
+[gitter-url]: https://gitter.im/juliadocs/users
 
-If you are using Windows and get an error `Provider PackageManager failed to satisfy dependency zmq`, you may need to restart Julia and run `Pkg.build("ZMQ")` again. See [issue #69](https://github.com/JuliaLang/ZMQ.jl/issues/69) for more details.
+[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
+[docs-dev-url]: https://juliainterop.github.io/ZMQ.jl/latest
+
+[docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
+[docs-stable-url]: https://juliainterop.github.io/ZMQ.jl/stable
+
+[travis-img]: https://api.travis-ci.org/JuliaInterop/ZMQ.jl.svg
+[travis-url]: https://travis-ci.org/JuliaInterop/ZMQ.jl
+
+[appveyor-img]: https://ci.appveyor.com/api/projects/status/u1d6dpovaptdqalh?svg=true
+[appveyor-url]: https://ci.appveyor.com/project/StevenGJohnson/zmq-jl
+
+[codecov-img]: https://codecov.io/gh/JuliaDocs/Documenter.jl/branch/master/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/JuliaDocs/Documenter.jl
+
+[issues-url]: https://github.com/JuliaDocs/Documenter.jl/issues

docs/.gitignore

@@ -0,0 +1 @@
+build/

docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+ZMQ = "c2297ded-f4af-51ae-bb23-16f91089e4e1"
+
+[compat]
+Documenter = "~0.20"

docs/make.jl

@@ -0,0 +1,21 @@
+using Documenter, ZMQ
+
+makedocs(
+    modules = [ZMQ],
+    sitename="ZMQ.jl",
+    authors = "Joel Frederico",
+    pages = [
+        "Home" => "index.md",
+        "Manual" => Any[
+            "Guide" => "man/guide.md",
+            "man/examples.md",
+        ],
+        "Reference" => "reference.md",
+    ],
+    #= Documenter.HTML(), =#
+)
+
+deploydocs(
+    repo = "github.com/JuliaInterop/ZMQ.jl.git",
+    target = "build",
+)

docs/src/index.md

@@ -0,0 +1,15 @@
+# ZMQ.jl
+
+*A Julia interface to ZeroMQ.*
+
+**ZMQ.jl** is a [Julia](http://julialang.org) interface to [ZeroMQ, The Intelligent Transport Layer](http://zeromq.org).
+
+## Package Features
+
+- Access ZeroMQ sockets from Julia
+
+The [Guide](@ref) provides a tutorial explaining how to get started using ZMQ.jl.
+
+Some examples of packages using Documenter can be found on the [Examples](@ref) page.
+
+See the [Reference](@ref) for the complete list of documented functions and types.

docs/src/man/examples.md

@@ -0,0 +1 @@
+# Examples

docs/src/man/guide.md

@@ -0,0 +1,27 @@
+# Guide
+
+## Usage
+
+```julia
+using ZMQ
+
+s1=Socket(REP)
+s2=Socket(REQ)
+
+bind(s1, "tcp://*:5555")
+connect(s2, "tcp://localhost:5555")
+
+send(s2, "test request")
+msg = recv(s1, String)
+send(s1, "test response")
+close(s1)
+close(s2)
+```
+
+The `send(socket, x)` and `recv(socket, SomeType)` functions make an extra copy of the data when converting
+between ZMQ and Julia.   Alternatively, for large data sets (e.g. very large arrays or long strings), it can
+be preferable to share data, with `send(socket, Message(x))` and `msg = recv(Message)`, where the `msg::Message`
+object acts like an array of bytes; this involves some overhead so it may not be optimal for short messages.
+
+(Help in writing more detailed documentation would be welcome!)
+

docs/src/reference.md

@@ -0,0 +1,4 @@
+# Reference
+
+```@index
+```