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?