mirror of
https://github.com/vale981/sphinx-multiversion
synced 2025-03-05 09:31:40 -05:00
60 lines
1.8 KiB
ReStructuredText
60 lines
1.8 KiB
ReStructuredText
|
.. _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/
|