From 1d6de3fc6b448b38f020b571fa5b86121c6c2b81 Mon Sep 17 00:00:00 2001 From: Joel Frederico <458871+joelfrederico@users.noreply.github.com> Date: Mon, 10 Dec 2018 13:13:52 -0800 Subject: [PATCH] Add docs to repo (#188) * First pass at adding docs * Update docs * Fix Manifest * Another docs fix * Direct URLs to JuliaInterop's repo --- .gitignore | 2 ++ .travis.yml | 13 +++++++- README.md | 69 ++++++++++++++++++++++++++-------------- docs/.gitignore | 1 + docs/Project.toml | 6 ++++ docs/make.jl | 21 ++++++++++++ docs/src/index.md | 15 +++++++++ docs/src/man/examples.md | 1 + docs/src/man/guide.md | 27 ++++++++++++++++ docs/src/reference.md | 4 +++ 10 files changed, 134 insertions(+), 25 deletions(-) create mode 100644 .gitignore create mode 100644 docs/.gitignore create mode 100644 docs/Project.toml create mode 100644 docs/make.jl create mode 100644 docs/src/index.md create mode 100644 docs/src/man/examples.md create mode 100644 docs/src/man/guide.md create mode 100644 docs/src/reference.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5733780 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +# Vim temporary files +*.sw? diff --git a/.travis.yml b/.travis.yml index bbf4a93..7f527a8 100644 --- a/.travis.yml +++ b/.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 diff --git a/README.md b/README.md index 2f0c650..f7ca5bc 100644 --- a/README.md +++ b/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 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..567609b --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +build/ diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 0000000..8fb9eee --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,6 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +ZMQ = "c2297ded-f4af-51ae-bb23-16f91089e4e1" + +[compat] +Documenter = "~0.20" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 0000000..c58fa21 --- /dev/null +++ b/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", +) diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 0000000..8cfa19f --- /dev/null +++ b/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. diff --git a/docs/src/man/examples.md b/docs/src/man/examples.md new file mode 100644 index 0000000..df635b4 --- /dev/null +++ b/docs/src/man/examples.md @@ -0,0 +1 @@ +# Examples diff --git a/docs/src/man/guide.md b/docs/src/man/guide.md new file mode 100644 index 0000000..998aa4e --- /dev/null +++ b/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!) + diff --git a/docs/src/reference.md b/docs/src/reference.md new file mode 100644 index 0000000..2dec9b1 --- /dev/null +++ b/docs/src/reference.md @@ -0,0 +1,4 @@ +# Reference + +```@index +```