Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
zfrenchee opened this issue Feb 2, 2017 · 15 comments

Comments

Projects
None yet
@zfrenchee
Copy link

commented Feb 2, 2017

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

This comment has been minimized.

Copy link
Member

commented Feb 2, 2017

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

This comment has been minimized.

Copy link
Member

commented Feb 3, 2017

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,

@tk0miya tk0miya closed this Feb 3, 2017

@tk0miya tk0miya added the question label Feb 3, 2017

@zfrenchee

This comment has been minimized.

Copy link
Author

commented Feb 3, 2017

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

@thamnos thamnos referenced this issue Jul 24, 2017

Open

Documentation #15

devdattakulkarni added a commit to cloud-ark/caastle that referenced this issue Aug 30, 2017

@suhailvs

This comment has been minimized.

Copy link

commented Jun 8, 2018

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

This comment has been minimized.

Copy link

commented Jun 28, 2018

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

This comment has been minimized.

Copy link

commented Jul 10, 2018

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

This comment has been minimized.

Copy link

commented Jul 27, 2018

@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

This comment has been minimized.

Copy link

commented Jul 31, 2018

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

This comment has been minimized.

Copy link

commented Oct 12, 2018

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?

aalexanderr added a commit to aalexanderr/muxpi that referenced this issue Oct 22, 2018

Adjust docs for github pages
* Renamed doc folder to docs
* Added docs/.nojekyll file
* Added docs/index.html with redirect to docs/html/index.html
* Moved docs/Makefile to repository root (and adjusted it
  consistently with rest of SamsungSLAV repositories)
* Moved docs/sphinx contents to docs/ directly
* Changed build directory from docs/build to docs/
* Moved docs/docker/Dockerfile for building documentation to
  docs/Dockerfile directory for consistency with other SamsungSLAV
  repositories
* Adjusted Makefile after directory changes

We should always link to: samsungslav.github.io/muxpi/html/
NOT to: samsungslav.github.io/muxpi/
(which works, but due to redirect is not SEO-friendly)

I had used this thread as reference:
sphinx-doc/sphinx#3382

Change-Id: I782507b8cdf1ffbdc8a8825a1530b9977bef196b
Signed-off-by: Alexander Mazuruk <a.mazuruk@samsung.com>

aalexanderr added a commit to aalexanderr/muxpi that referenced this issue Oct 22, 2018

Adjust docs for github pages
* Renamed doc folder to docs
* Added docs/.nojekyll file
* Added docs/index.html with redirect to docs/html/index.html
* Moved docs/Makefile to repository root (and adjusted it
  consistently with rest of SamsungSLAV repositories)
* Moved docs/sphinx contents to docs/ directly
* Changed build directory from docs/build to docs/
* Moved docs/docker/Dockerfile for building documentation to
  docs/Dockerfile directory for consistency with other SamsungSLAV
  repositories
* Adjusted Makefile after directory changes

We should always link to: samsungslav.github.io/muxpi/html/
NOT to: samsungslav.github.io/muxpi/
(which works, but due to redirect is not SEO-friendly)

I had used this thread as reference:
sphinx-doc/sphinx#3382

Change-Id: I782507b8cdf1ffbdc8a8825a1530b9977bef196b
Signed-off-by: Alexander Mazuruk <a.mazuruk@samsung.com>
@qwilka

This comment has been minimized.

Copy link

commented Jan 4, 2019

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 tk0miya reopened this Jan 4, 2019

@tk0miya

This comment has been minimized.

Copy link
Member

commented Jan 4, 2019

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

@tk0miya tk0miya added the help wanted label Jan 4, 2019

@TimKam

This comment has been minimized.

Copy link
Member

commented Jan 4, 2019

I will try to help.

@TimKam TimKam self-assigned this Jan 4, 2019

@jason-huling

This comment has been minimized.

Copy link

commented Mar 8, 2019

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.

folker added a commit to folker/tech-report that referenced this issue Mar 25, 2019

restructed according to sphinx-doc/sphinx#3382
In your project repo create two directories, docsrc and docs.
In docsrc, initialize sphinx.
Add docsrc/_build/ to your .gitignore
Add the following to the Makefile that sphinx generated for you under docsrc/Makefile
github:
    @make html
    @cp -a _build/html/. ../docs
Then you can run make github from the docsrc directory to generate the docs and move them to where GitHub wants them.
@H4dr1en

This comment has been minimized.

Copy link

commented Apr 23, 2019

@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

This comment has been minimized.

Copy link

commented Apr 23, 2019

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

yelizariev added a commit to it-projects-llc/odoo-test that referenced this issue Apr 30, 2019

robvanholstein added a commit to robvanholstein/IRDAP that referenced this issue May 11, 2019

Second attempt to create website
sphinx-doc/sphinx#3382

Look at suhailvs commented on Jun 8, 2018

benmack added a commit to benmack/nasa_hls that referenced this issue May 18, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.