|
|
@@ -0,0 +1,59 @@
|
|
|
+.. _github_pages:
|
|
|
+
|
|
|
+=======================
|
|
|
+Hosting on GitHub Pages
|
|
|
+=======================
|
|
|
+
|
|
|
+You use `GitHub Pages <github_pages_website_>`_ to host documentation generated by ``sphinx-multiversion``.
|
|
|
+
|
|
|
+Setting up the ``gh-pages`` Branch
|
|
|
+==================================
|
|
|
+
|
|
|
+First, you need to create a ``gh-pages`` branch and disable Jekyll.
|
|
|
+
|
|
|
+.. code-block:: bash
|
|
|
+
|
|
|
+ git checkout --orphan gh-pages
|
|
|
+ touch .nojekyll
|
|
|
+ git add .nojekyll
|
|
|
+ git commit -m "Disable Jekyll"
|
|
|
+
|
|
|
+Then, switch back to the branch you were on and build the documentation using ``sphinx-multiversion``:
|
|
|
+
|
|
|
+.. code-block:: bash
|
|
|
+
|
|
|
+ mkdir html
|
|
|
+ sphinx-multiversion docs/ html/
|
|
|
+
|
|
|
+If everything worked fine, you now need to switch back to your ``gh-pages`` branch and commit the data there:
|
|
|
+
|
|
|
+.. code-block:: bash
|
|
|
+
|
|
|
+ git checkout gh-pages
|
|
|
+ for dirname in html/*; do mv "html/$dirname" "$dirname" && git add "$dirname"; done
|
|
|
+ git commit -m "Added HTML docs"
|
|
|
+ git push origin gh-pages
|
|
|
+
|
|
|
+Now your documentation should already be online.
|
|
|
+You can navigate to ``https://username.github.io/reponame/master/`` to see the documentation for the master branch.
|
|
|
+
|
|
|
+Redirecting from the Document Root
|
|
|
+==================================
|
|
|
+
|
|
|
+You can easily redirect users that type ``https://username.github.io/reponame/`` into their addressbar to the documentation for any version you like.
|
|
|
+Just add a :file:`index.html` file to the root directory of your ``gh-pages`` branch:
|
|
|
+
|
|
|
+.. code-block:: html
|
|
|
+
|
|
|
+ <!DOCTYPE html>
|
|
|
+ <html>
|
|
|
+ <head>
|
|
|
+ <title>Redirecting to master branch</title>
|
|
|
+ <meta charset="utf-8">
|
|
|
+ <meta http-equiv="refresh" content="0; url=./master/">
|
|
|
+ <link rel="canonical" href="https://username.github.io/reponame/master/">
|
|
|
+ </head>
|
|
|
+ </html>
|
|
|
+
|
|
|
+
|
|
|
+.. _github_pages_website: https://pages.github.com/
|
Jan Holthuis