How to use github pages from master /docs folder elegantly with sphinx

[alexlenail]

Problem

What I'd like to do is in the master branch of my github repo, have a /docs directory which within it, has a sphinx project. I'd like to be able to update the docs with only a cd docs and make html. Github pages doesn't allow you to choose arbitrary directories, otherwise I would set github pages to use /docs/build/html.

My principal question is: is it possible to use the command make html without creating a new html folder, but dump all the files in the directory specified by the BUILDDIR variable in the Makefile? Is there an option in SPHINXBUILD which will let me do this?

My more general question is: how do people in practice using github pages (from master branch, /docs folder) set up sphinx? I can't seem to find documentation of anyone trying to accomplish this, and the documentation to do related things (e.g. using a gh-pages branch) seems kind of out of date.

Thanks!

[TimKam]

It's generally disputable whether committing build results is elegant.

This question aside, here's a solution:

1. In your project config, choose to use the docs folder for your GitHub Pages.

2. Change the Sphinx build directory in your Makefilefor example as follows:

   BUILDDIR      = .
   

   In my attempts, I couldn't keep _build, probably because GitHub Pages didn't like the underscore _ prefix.

3. In the docs folder, create an index.html file and redirect to ./html/index.html (or whatever build directory you have configured, for example like this:

   <meta http-equiv="refresh" content="0; url=./html/index.html" />
   

   Note there are probably more elegant/backwards-compatible/SEO-friendly ways to handle redirects.

[tk0miya]

Sorry, this is a bug tracker of Sphinx, not a forum.
Please move https://groups.google.com/forum/#!forum/sphinx-users .

BTW, I feel BUILDDIR = . is dangerous. It causes documents lost by make clean...
So I recommend to use BUILDDIR = build/ or other directories (not having underscores).

Please let me know if you get a good way to do that. I will add it to our document.

Thanks,

[alexlenail]

Sorry @tk0miya ! Thanks @TimKam ! The redirect idea was what I was missing.

[suhailvs]

Update of @TimKam

This worked fine for me.

1. Create a folder docs in the root path.

2. By default, Jekyll does not build any files or directories with underscore. Include an empty .nojekyll file in the docs folder to turn off Jekyll.

3. In the docs folder, create an index.html file and redirect to ./html/index.html for example like this:

<meta http-equiv="refresh" content="0; url=./html/index.html" />

4. Change the Sphinx build directory to docs in your Makefile for example as follows:

BUILDDIR = docs

5. Run make html then add, commit and push the repo.

6. In your project config, choose to use the docs folder for your GitHub Pages.

7. visit https://<username>.github.io/<repo>

[ritabratamaiti]

Sorry to bump an old issue but.... I am currently using @suhailvs (Tysm ^_^) method and it's working fine like GitHub docs are being built like this: https://ritabratamaiti.github.io/RapidML and the readthedocs page is working fine too: https://rapidml.readthedocs.io/en/latest/
The only issue right now is how SEO friendly is the redirect method, like will search engine bots follow through the links and if not how to solve the issue....

[KellyBlack]

We use the method detailed by @suhailvs (Thank you!) and it works fine as well. With respect to the question of SEO when we publish links to the documentation we do not use the https://.github.io/ url but rather the https://.github.io//html/ url. We put the later url in the README.md file in the main repo as well.

That way web crawlers should go directly to the sphinx pages without the redirect. The redirect as given in the last step by @suhailvs is simply a convenience step for people used to the jekyll way of doing things.

[wxianxin]

@suhailvs Thanks! I only:

1. create .nojekyll
2. create and change the index.html content to <meta http-equiv="refresh" content="0; url=./build/html/index.html" />

And I don't need to do anything else, just make html. It works like a charm.

[suhailvs]

update of @wxianxin

1. Create an empty .nojekyll file in the root folder to turn off Jekyll.
2. Create an index.html file in the root folder with contents:
   <meta http-equiv="refresh" content="0; url=./_build/html/index.html" />
3. Run make html then add, commit and push the repo.
4. In the GitHub Pages box in the project Settings page, choose to use master branch.
5. Visit https://<username>.github.io/<repo>

[songololo]

Can we please reopen this issue?

I realise it was previously closed per not being a forum, though isn't there a legitimate case for providing the option to build the HTML to a specific directory for compatibility with GitHub pages?

[qwilka]

Having just spent a lot of time trying to get Sphinx documentation to render correctly on Github Pages before belatedly discovering the working procedure described above by @suhailvs, I would support the call to re-open this issue until it is resolved by updating the documentation and upgrading the currently ineffective «githubpages» extension.

[tk0miya]

Reopened. But I don't understand what I should do. Can anyone send a PR for this?

[TimKam]

I will try to help.

[jason-huling]

Hey, idk if this is any better, or maybe even worse than the redirect approach, but another option that worked for me...

1. In your project repo create two directories, docsrc and docs.
2. In docsrc, initialize sphinx.
3. Add docsrc/_build/ to your .gitignore
4. Add the following to the Makefile that sphinx generated for you under docsrc/Makefile

   github:
       @make html
       @cp -a _build/html/. ../docs
   

5. Then you can run make github from the docsrc directory to generate the docs and move them to where GitHub wants them.

This approach also helps to avoid committing other build artifacts that you may not want to commit, like the doctrees pickle files.

[H4dr1en]

@jason-huling ,

By adding the github option in the Makefile, running make github throws me the following error:

Running Sphinx v2.0.1
Sphinx error:
Builder name github not registered or available through entry point

How did you address this error?

[H4dr1en]

So I figured out: if you are on Windows, then you should edit your make.bat rather than your Makefile and add:

if "%1" == "github" (
    %SPHINXBUILD% -M html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
    robocopy %BUILDDIR%/html ../docs /E > nul
    echo.Generated files copied to ../docs
    goto end
)

After the following line:

if "%1" == "" goto help

And then you can enter make github, which will be equivalent to make html and then copy generated files into ../docs

[johnthagen]

MkDocs has a built in gh-deploy function to make this easy for new beginners. Perhaps something similarly simple could be added to Sphinx?

[Darel13712]

MkDocs has a built in gh-deploy function to make this easy for new beginners. Perhaps something similarly simple could be added to Sphinx?

Hey, @johnthagen , your comment reminded me of how I love mkdocs for this feature and how badly I miss it with sphinx. Mkdocs use ghp-import package to add this functionality and it can be easily added yourself, improving on @jason-huling approach.

Here is what you need to do:

1. pip install ghp-import
2. Have your sphinx files in the usual folder. docs for example.
3. Update your sphinx Makefile with new make command

gh-deploy:
    @make html
    @ghp-import _build/html -p -o -n

4. Now when you run make gh-deploy it will build docs, copy them to your gh-pages branch, add .nojekyll file for you, and push new version.
5. Don't forget to setup pages to look at the root of your gh-pages branch for built site.

[ntn888]

Hey, idk if this is any better, or maybe even worse than the redirect approach, but another option that worked for me...

1. In your project repo create two directories, `docsrc` and `docs`.

2. In `docsrc`, initialize sphinx.

3. Add `docsrc/_build/` to your `.gitignore`

4. Add the following to the Makefile that sphinx generated for you under `docsrc/Makefile`
   ```
   github:
       @make html
       @cp -a _build/html/. ../docs
   ```

5. Then you can run `make github` from the `docsrc` directory to generate the docs and move them to where GitHub wants them.

This approach also helps to avoid committing other build artifacts that you may not want to commit, like the doctrees pickle files.

you may want to run before @cp create a new line with:

@rm -rf ../docs/*

[gnikit]

I am not sure why this has not been mentioned but using GitHub Actions this has a quite elegant solution.
The following Action will build (make html) whenever there is a code change but publish your page, only for master.

name: "Documentation"
on: [push, pull_request]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: sphinx-toolbox/sphinx-action@master
        with:
          pre-build-command: "pip install .[docs]"
          docs-folder: "docs/"
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/master'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/_build/html

As a side note, there are a few different Actions that can be used to deploy to github pages but peaceiris/actions-gh-pages@v3 is the only one I found that allows you to cd into a subdirectory and call make html. This effectively allows you to have your documentation dependencies on your project's root directory instead of having them within docs.

[AA-Turner]

Summarised actionable content from this issue in #10472.

A