Added github pages documentation

.travis.yml

@@ -2,14 +2,30 @@ language: java
 dist: trusty
 sudo: false
 
+env:
+  global:
+    - secure: VRPA9iYt/qXZU2VGlP0AKN0IcfOWtM8N2z4/mBbCaM6GAff6SYTRlfvjtUStvNgfJAig5T81fnYAyObT/3HyaDEYjyxWnaAqWaNJ4vHG/S2T9ajlVPg3udviQPXHQZOQ0co2+NUzwpJhuv5LLQYuMvwNszIiXWHSbOlDA1wLTsfJzvS7sSeLzDbi5fBffjwg6n1RQUsXEHbRokrHNFRX2ovxeXlONRTTMVaRq/rnJx8HFkHaj/6fdC2wOXE342RC+N/LbdzLVRzNzFNC1gSgRXU2NBhaKLXV4/xRucLJ+mHm/xeFZTmoeFAyHpUQEPPxEu/ogV/7aSxvqYX+N+6g0SkZn+JzKDSf/L7qnv8BKmlc04Mo6OncLVTtJgZYgUZtbVloRhnl5Xo0SdzonzYNQGZHvcCg5y0tljYe3Z5JXmE/dSwYl+LeoY7B2ImMFI0MPvjr83EnbSRRLoDZBiY0jFtrwB8hsIQ/QSVHLABCmlOWiQnOhIcZ1BqhBNUFKbXgDEBZnNSB78wW4ZjlPXFzWYYuVfJOnel+UugoJ49KmrT7W3BQOh+sUICJd8tDYakQR2ysYS9OY9985yRnYinJddFma4e6yKbcD5j6MU71/FwXvcu5ncjpxpAUOSlnDryTm3mp42lTikM1ojD/MNyi4de8Sr9zgDMTe+0LjsayYxU=
+
+addons:
+  apt:
+    update: true
+
 matrix:
   include:
     - name: "Java 8 Tests"
       jdk: oraclejdk8
     - name: "Coverage"
       jdk: oraclejdk8
-      env: TESTENV=cover
+      env: TESTENV=cover FYI="this also builds documentation for tags"
       script: mvn clean cobertura:cobertura
+      addons:
+        apt:
+          packages:
+            - python3
+            - python3-pip
+            - python-virtualenv
+            - make
 
 after_success:
-  - '[ "$TESTENV" == "cover" ] && bash <(curl -s https://codecov.io/bash)'
+  - '[[ "$TESTENV" == "cover" ]] && bash <(curl -s https://codecov.io/bash)'
+  - '[[ "$TESTENV" == "cover" ]] && [[ -n "$TRAVIS_TAG" ]] && ./deploy-docs.sh'

README.md

@@ -5,6 +5,9 @@ This is the Engine.IO Server Library for Java ported from the [JavaScript server
 
 See also: [Engine.IO-client Java](https://github.com/socketio/engine.io-client-java)
 
+## Documentation
+Complete documentation can be found [here](https://socketio.github.io/engine.io-server-java/).
+
 ## Installation
 This section will be updated when artifact is available on Maven Central.
 

deploy-docs.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+
+# This script builds the documentation and pushes it to github
+
+AUTHOR="Documentation Builder"
+GH_REPO_REF="github.com/$TRAVIS_REPO_SLUG"
+
+set -e
+
+cd docs
+
+# Activate virtualenv
+virtualenv -p python3 venv
+. venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Build docs
+make html
+
+cd _build
+
+# Configure git
+git config --global push.default simple
+git config user.name "Travis CI"
+git config user.email "travis@travis-ci.org"
+
+# Clone docs branch
+git clone -b gh-pages https://git@$GH_REPO_REF docs-upload
+cd docs-upload
+
+# Remove existing docs
+rm -rf *
+
+# Copy docs from build to repo
+cp -r ../html/* ./
+echo "" > .nojekyll
+
+if [[ -f "index.html" ]]; then
+    # Commit
+    git add --all
+    git commit -m "Deploy code docs to GitHub Pages Travis build"
+
+    git push --force "https://${GH_REPO_TOKEN}@${GH_REPO_REF}" > /dev/null 2>&1
+else
+    echo 'ERROR: index.html not found'
+    exit 1
+fi

docs/.gitignore

@@ -0,0 +1 @@
+/_build

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = EngineIO
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_themes/sphinx_rtd_theme/__init__.py

@@ -0,0 +1,19 @@
+"""Sphinx ReadTheDocs theme.
+
+From https://github.com/ryan-roemer/sphinx-bootstrap-theme.
+
+"""
+from os import path
+
+__version__ = '0.4.1'
+__version_full__ = __version__
+
+
+def get_html_theme_path():
+    """Return list of HTML theme paths."""
+    cur_dir = path.abspath(path.dirname(path.dirname(__file__)))
+    return cur_dir
+
+# See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package
+def setup(app):
+    app.add_html_theme('sphinx_rtd_theme', path.abspath(path.dirname(__file__)))

docs/_themes/sphinx_rtd_theme/breadcrumbs.html

@@ -0,0 +1,82 @@
+{# Support for Sphinx 1.3+ page_source_suffix, but don't break old builds. #}
+
+{% if page_source_suffix %}
+{% set suffix = page_source_suffix %}
+{% else %}
+{% set suffix = source_suffix %}
+{% endif %}
+
+{% if meta is defined and meta is not none %}
+{% set check_meta = True %}
+{% else %}
+{% set check_meta = False %}
+{% endif %}
+
+{% if check_meta and 'github_url' in meta %}
+{% set display_github = True %}
+{% endif %}
+
+{% if check_meta and 'bitbucket_url' in meta %}
+{% set display_bitbucket = True %}
+{% endif %}
+
+{% if check_meta and 'gitlab_url' in meta %}
+{% set display_gitlab = True %}
+{% endif %}
+
+<div role="navigation" aria-label="breadcrumbs navigation">
+
+  <ul class="wy-breadcrumbs">
+    {% block breadcrumbs %}
+      <li><a href="{{ pathto(master_doc) }}">{{ _('Docs') }}</a> &raquo;</li>
+        {% for doc in parents %}
+          <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</li>
+        {% endfor %}
+      <li>{{ title }}</li>
+    {% endblock %}
+    {% block breadcrumbs_aside %}
+      <li class="wy-breadcrumbs-aside">
+        {% if hasdoc(pagename) %}
+            {% if display_github %}
+            {% if check_meta and 'github_url' in meta %}
+              <!-- User defined GitHub URL -->
+              <a href="{{ meta['github_url'] }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+            {% else %}
+              <a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+            {% endif %}
+          {% elif display_bitbucket %}
+            {% if check_meta and 'bitbucket_url' in meta %}
+              <!-- User defined Bitbucket URL -->
+              <a href="{{ meta['bitbucket_url'] }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
+            {% else %}
+              <a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}{{ suffix }}?mode={{ theme_vcs_pageview_mode|default("view") }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
+            {% endif %}
+          {% elif display_gitlab %}
+            {% if check_meta and 'gitlab_url' in meta %}
+              <!-- User defined GitLab URL -->
+              <a href="{{ meta['gitlab_url'] }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a>
+            {% else %}
+              <a href="https://{{ gitlab_host|default("gitlab.com") }}/{{ gitlab_user }}/{{ gitlab_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ gitlab_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a>
+            {% endif %}
+          {% elif show_source and source_url_prefix %}
+            <a href="{{ source_url_prefix }}{{ pagename }}{{ suffix }}">{{ _('View page source') }}</a>
+          {% elif show_source and has_source and sourcename %}
+            <a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow"> {{ _('View page source') }}</a>
+          {% endif %}
+        {% endif %}
+      </li>
+    {% endblock %}
+  </ul>
+
+  {% if (theme_prev_next_buttons_location == 'top' or theme_prev_next_buttons_location == 'both') and (next or prev) %}
+  <div class="rst-breadcrumbs-buttons" role="navigation" aria-label="breadcrumb navigation">
+      {% if next %}
+        <a href="{{ next.link|e }}" class="btn btn-neutral float-right" title="{{ next.title|striptags|e }}" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
+      {% endif %}
+      {% if prev %}
+        <a href="{{ prev.link|e }}" class="btn btn-neutral" title="{{ prev.title|striptags|e }}" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
+      {% endif %}
+  </div>
+  {% endif %}
+  <hr/>
+</div>

docs/_themes/sphinx_rtd_theme/footer.html

@@ -0,0 +1,52 @@
+<footer>
+  {% if (theme_prev_next_buttons_location == 'bottom' or theme_prev_next_buttons_location == 'both') and (next or prev) %}
+    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
+      {% if next %}
+        <a href="{{ next.link|e }}" class="btn btn-neutral float-right" title="{{ next.title|striptags|e }}" accesskey="n" rel="next">{{ _('Next') }} <span class="fa fa-arrow-circle-right"></span></a>
+      {% endif %}
+      {% if prev %}
+        <a href="{{ prev.link|e }}" class="btn btn-neutral" title="{{ prev.title|striptags|e }}" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> {{ _('Previous') }}</a>
+      {% endif %}
+    </div>
+  {% endif %}
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>
+    {%- if show_copyright %}
+      {%- if hasdoc('copyright') %}
+        {% trans path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}
+      {%- else %}
+        {% trans copyright=copyright|e %}&copy; Copyright {{ copyright }}.{% endtrans %}
+      {%- endif %}
+    {%- endif %}
+
+    {%- if build_id and build_url %}
+      {% trans build_url=build_url, build_id=build_id %}
+        <span class="build">
+          Build
+          <a href="{{ build_url }}">{{ build_id }}</a>.
+        </span>
+      {% endtrans %}
+    {%- elif commit %}
+      {% trans commit=commit %}
+        <span class="commit">
+          Revision <code>{{ commit }}</code>.
+        </span>
+      {% endtrans %}
+    {%- elif last_updated %}
+      {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
+    {%- endif %}
+
+    </p>
+  </div>
+
+  {%- if show_sphinx %}
+  {% trans %}Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>{% endtrans %}.
+  {%- endif %}
+
+  {%- block extrafooter %} {% endblock %}
+
+</footer>
+