[zeromq-dev] cppzmq "tour"

[Brett Viren]

Hi Kevin,

Kevin Sapper <kevinsapper88 at gmail.com> writes:

> wow fantastic tour :)

Thanks!  And thanks also for the kind words from everyone else.

> I would love this to become part of the official cppzmq documentation. At least you should add
> a link in the cppzmq README ;)

Yes, I have been thinking of how to suggest putting it somewhere under a
ZeroMQ namespace.  Let me suggest two options and see what people think.

Option 1) The least effort option is to fork cppzmq-tour into the ZeroMQ
GitHub organization and expose that repo as a GitHub page, just like is
done for the current website.  This would serve the tour at:

  https://zeromq.github.io/cppzmq-tour

Option 2a) with a little bit more file wrangling and a PR the "tour"
content can be copied into cppzmq repo, say under docs/tour/, and we can
then expose the cppzmq repo as a GitHub page.  This would put the tour
at:

  https://zeromq.github.io/cppzmq/docs/tour

In this option we should provide at least a top-level "landing" page.
It would be committed to the source tree as cppzmq/index.html.  We might
generate it from cppzmq/README.md (eg with pandoc) or make it from
scratch.

Option 2b) A variant here is that instead of exposing the entire repo as
the URL we expose just the cppzmq/docs/ directory.  This would keep
.html files out of the top-level source directory, docs/index.html would
provide the landing and the tour would show up as:

  https://zeromq.github.io/cppzmq/tour

The only minor downside with exposing just the cppzmq/docs/ as the
website is that source isn't served under the site's URL.

I'm happy to work toward either approaches and I'm open to other ideas.


One note, the "tour" content itself poses some small requirements.  The
source is written in orgmode markup and the HTML is exported from that
via Emacs.  Pandoc conversion may also work but I've not tried it.  I'd
like to keep the source as orgmode if I will continue to edit.  The page
theme is provided by some CSS/JS files from fniessen/org-html-themes as
well as usual 3rd party suspects (bootstrap/jquery).  I've include
copies of the 3rd party files (taken from org-html-themes) directly into
the repo/webpage so that blockers like uMatrix don't get angry being
asked to load from 3rd party servers.


Wherever it ends up, yes, I agree a link in cppzmq/README.md will help
others find it.  Once we figure out a final spot, I'm happy to make a PR
to add one.

-Brett.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 832 bytes
Desc: not available
URL: <https://lists.zeromq.org/pipermail/zeromq-dev/attachments/20200416/d860cf4e/attachment.sig>