Sphinx: 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" />

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

BUILDDIR = docs

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

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

3. 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