DragonOS-Community
/
sphinx-multiversion
spiegel van https://github.com/DragonOS-Community/sphinx-multiversion


			
				
					
						
						
							1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889
							.. _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/