mirror of
https://github.com/vale981/sphinx-multiversion
synced 2025-03-04 17:11:39 -05:00
89 lines
2.7 KiB
ReStructuredText
89 lines
2.7 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/index.html">
|
|
<link rel="canonical" href="https://username.github.io/reponame/master/index.html">
|
|
</head>
|
|
</html>
|
|
|
|
Automating documentation builds with Travis CI
|
|
==============================================
|
|
|
|
You can also automate versioned builds using Travis CI.
|
|
To do that, add this to your :file:`.travis.yml` file:
|
|
|
|
.. code-block:: yaml
|
|
|
|
script:
|
|
# Build documentation
|
|
- mkdir html
|
|
- sphinx-multiversion docs/ html/
|
|
|
|
before_deploy:
|
|
# Add .nojekyll file and redirect from docroot to the sphinx output dir
|
|
- touch html/.nojekyll
|
|
- cp assets/gh-pages-redirect.html html/index.html
|
|
|
|
deploy:
|
|
# Only deploy the sphinx output dir as gh-pages branch
|
|
- provider: pages
|
|
skip_cleanup: true
|
|
github_token: $GITHUB_TOKEN
|
|
keep_history: false
|
|
local_dir: html
|
|
|
|
.. seealso::
|
|
|
|
For details, please have a look at the `GitHub Pages Deployment documentation for Travis CI <travis_gh_pages_deployment_>`_.
|
|
|
|
.. _github_pages_website: https://pages.github.com/
|
|
.. _travis_gh_pages_deployment: https://docs.travis-ci.com/user/deployment/pages/
|