Migrate from GitHub pages to Read the Docs

zoni · zoni · commit 28b3397ff466 · 2016-02-28T16:59:41.000+01:00
This changes the documentation build process to work on Read the Docs. Included are style changes to give the RTD version selection box a different style which is consistent with our custom website theme. The docs readme has been updated and the sphinx makefile has had its gh-pages specific rules removed. Preview available at http://errbot.readthedocs.org/
diff --git a/.gitignore b/.gitignore
@@ -11,7 +11,6 @@ nohup.out
 /config-*.egg
 /config*.py
 /docs/_build
-/docs/_gh-pages
 /docs/errbot.rst
 /docs/errbot.*.rst
 /.cache
diff --git a/docs/Makefile b/docs/Makefile
@@ -4,11 +4,8 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-SPHINXAPIDOC  = sphinx-apidoc
 PAPER         =
 BUILDDIR      = _build
-PAGESURL      = git@github.com:errbotio/errbot.git
-PAGESDIR      = _gh-pages
 EXTRADIR      = _extra
 
 # User-friendly check for sphinx-build
@@ -23,7 +20,7 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext gh-pages apidoc
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -53,25 +50,12 @@ help:
 clean:
 	rm -rf $(BUILDDIR)/*
 
-gh-pages: clean apidoc html
-	test -e $(PAGESDIR) && (cd $(PAGESDIR) && git pull) || git clone $(PAGESURL) $(PAGESDIR)
-	cd $(PAGESDIR) && git checkout gh-pages
-	rm -rf $(PAGESDIR)/*
-	cp -r $(BUILDDIR)/html/* $(PAGESDIR)/
-	cp -r $(EXTRADIR)/* $(EXTRADIR)/.nojekyll $(PAGESDIR)/
-	cd $(PAGESDIR) && git add --all . && git commit --message "Sphinx autobuild"
-	@echo
-	@echo "GitHub pages are built and ready, just waiting to be pushed from the $(PAGESDIR) directory"
-
-apidoc:
-	$(SPHINXAPIDOC) --separate -f -o . ../errbot
-
-html: apidoc
+html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-dirhtml: apidoc
+dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
diff --git a/docs/README.rst b/docs/README.rst
@@ -5,43 +5,35 @@ Errbot's website and documentation are built using `Sphinx`_. Useful
 references when contributing to the docs are the `reStructuredText Primer`_
 and `Inline markup`_ documents.
 
+
 Requirements
 ------------
 
 Documentation *must* be built using Python 3. Additionally, extra requirements
-must be installed, which may be done through `pip install -r requirements.txt`.
+must be installed, which may be done through `pip install -r docs/requirements.txt`
+(note: you must run this from the root of the repository).
 
 You must also have make installed in order to use the supplied Makefile.
 
+
 Building and viewing locally
 ----------------------------
 
 With the necessary requirements installed, the documentation can be built using
 the command `make html`. Once generated, the resulting pages can be viewed by
 opening `_build/html/index.html` in your webbrowser of choice.
 
-Publishing to GitHub pages
---------------------------
-
-*Note: This is only relevant to project maintainers*
-
-The `make gh-pages` command can be used to build output for GitHub pages. This
-will pull down a copy of the repository and auto-commit to the gh-pages branch.
-The results of this can then be reviewed before being pushed.
 
-There is a `Jenkins job <https://jenkins.errbot.net/job/Publish%20errbot.io/>`_
-which will do all of the above automatically on commits.
-Whenever a new version of errbot is released, the version number on this Jenkins
-job will need to be updated
-(look for *"Branch Specifier"* under *"Branches to build"*).
+Publishing to Read the Docs
+---------------------------
 
+*Note: This is only relevant to project maintainers*
 
-Including extra files with GitHub pages
----------------------------------------
+Read the Docs should rebuild the site automatically when new commits are pushed.
+When new project releases are made, it may be necessary to add the new version
+and remove older versions (to prevent clutter in the version drop-down).
+This can be done at https://readthedocs.org/dashboard/errbot/versions/.
 
-All the files found within the `_extra` directory are copied to the root of
-the output directory (after a successful Sphinx build) during the processing
-of `make gh-pages`.
 
 .. _Sphinx: http://sphinx-doc.org/
 .. _reStructuredText Primer: http://sphinx-doc.org/rest.html
diff --git a/docs/_extra/.nojekyll b/docs/_extra/.nojekyll
diff --git a/docs/_extra/CNAME b/docs/_extra/CNAME
diff --git a/docs/_extra/version b/docs/_extra/version
diff --git a/docs/_themes/err/layout.html b/docs/_themes/err/layout.html
@@ -3,14 +3,6 @@
     <!doctype html>
 {% endblock %}
 {%- block extrahead %}
-    <script type="text/javascript">
-        // GitHub pages offers no way to redirect to a canonical location, so we
-        // have to make do with hacky javascript redirection :(
-        if (document.location.protocol != "file:" && document.location.host != "errbot.io") {
-            var path = document.location.pathname.replace('/err/', '/');
-            document.location = "http://errbot.io" + path;
-        }
-    </script>
     <link rel="icon" type="image/png" href="{{ pathto('_static/err.png', 1) }}"/>
     <link rel="apple-touch-icon" href="{{ pathto('_static/err.png', 1) }}"/>
     <link rel="stylesheet" href="{{ pathto('_static/' ~ "fancybox/jquery.fancybox.css", 1) }}" type="text/css"
@@ -44,9 +36,9 @@
         <img class="logo" src="{{ pathto('_static/err_speech.png', 1) }}" width="220" height="135" alt="Logo of Err"/>
     </a>
     <div class="ghbuttons">
-        <iframe src="http://ghbtns.com/github-btn.html?user=errbotio&repo=errbot&type=watch&count=true"
+        <iframe src="//ghbtns.com/github-btn.html?user=errbotio&repo=errbot&type=watch&count=true"
                 allowtransparency="true" frameborder="0" scrolling="0" width="95" height="20"></iframe>
-        <iframe src="http://ghbtns.com/github-btn.html?user=errbotio&repo=errbot&type=fork&count=true" allowtransparency="true"
+        <iframe src="//ghbtns.com/github-btn.html?user=errbotio&repo=errbot&type=fork&count=true" allowtransparency="true"
                 frameborder="0" scrolling="0" width="95" height="20"></iframe>
     </div>
 {%- endblock %}
diff --git a/docs/_themes/err/static/err.css_t b/docs/_themes/err/static/err.css_t
@@ -9,11 +9,12 @@
 {% set code_font = "'Droid Sans Mono', monospace" %}
 {% set normal_link_color = "#f07e2a" %}
 {% set normal_link_hover_color = "#f07e2a" %}
+{% set highlight_color = "#f07e2a" %}
 
 /* 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; */
 
 @import url("basic.css");
-@import url(http://fonts.googleapis.com/css?family=Open+Sans|Droid+Sans+Mono);
+@import url(//fonts.googleapis.com/css?family=Open+Sans|Droid+Sans+Mono);
 
 /* -- page layout ----------------------------------------------------------- */
  
@@ -465,7 +466,9 @@ div.screenshots a {
         display: none;
     }
 
-
+    html body div.indexwrapper div.related ul li.right {
+        padding: 10px 0 20px;
+    }
 
 }
 
@@ -627,3 +630,71 @@ body #prev_next_links {
     padding: 0;
     text-align: center;
 }
+
+
+/* -- Gitter sidecar button ------------------------------------------------- */
+
+.gitter-open-chat-button {
+    background-color: {{ highlight_color }} !important;
+}
+
+
+/* -- Read the Docs version selector ---------------------------------------- */
+
+.rst-versions .rst-current-version {
+    color: #fff !important;
+    background: {{ highlight_color }} !important;
+}
+
+.rst-versions.rst-badge.shift-up .rst-current-version {
+    border-bottom-left-radius: 0;
+    border-bottom-right-radius: 0;
+}
+
+.rst-versions.rst-badge.shift-up .rst-current-version .fa-book {
+    float: none !important;
+}
+
+.rst-versions .rst-other-versions hr {
+    border-color: #fafafa !important;
+}
+
+.rst-versions.rst-badge .rst-current-version {
+    color: #fff !important;
+    background: {{ highlight_color }} !important;
+    position: fixed !important;
+    right: 35px !important;
+    top: 0 !important;
+    padding: 1px 15px !important;
+    border-bottom-left-radius: 0.5em;
+    border-bottom-right-radius: 0.5em;
+}
+
+.rst-versions .rst-other-versions {
+    color: #fff !important;
+    background: {{ highlight_color }} !important;
+    position: fixed !important;
+    right: 35px !important;
+    top: 30px !important;
+    border-top-left-radius: 0.5em;
+    border-bottom-left-radius: 0.5em;
+    border-bottom-right-radius: 0.5em;
+}
+
+.rst-versions a {
+    text-decoration: underline;
+    color: #fff !important;
+}
+
+.rst-versions .rst-other-versions dl dt {
+    text-decoration: underline;
+    font-style: italic;
+}
+
+.rst-versions .rst-other-versions a {
+    text-decoration: underline;
+}
+
+.rst-versions .rst-other-versions dl dd a {
+    text-decoration: none;
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -12,7 +12,7 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import subprocess, sys, os
 sys.path.append(os.path.abspath('_themes'))
 sys.path.append(os.path.abspath('_themes/err'))
 sys.path.append(os.path.abspath('../'))
@@ -115,6 +115,11 @@ def autodoc_skip_member(app, what, name, obj, skip, options):
         return False
     return skip
 
+# -- Apidoc --------------------------------------------------------------------
+
+def run_apidoc(_):
+    subprocess.check_call("sphinx-apidoc --separate -f -o . ../errbot", shell=True)
+
 # -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -309,3 +314,4 @@ def autodoc_skip_member(app, what, name, obj, skip, options):
 
 def setup(app):
     app.connect("autodoc-skip-member", autodoc_skip_member)
+    app.connect("builder-inited", run_apidoc)
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -4,7 +4,7 @@ sphinx>=1.2
 # is fixed and included into a new release.
 https://github.com/zoni/sphinx-autodoc-annotation/archive/issue-2.zip
 
--e ../.
+-e .
 sleekxmpp
 irc
 pyfire
