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
alexlenail opened this issue Feb 2, 2017 · 17 comments
Open

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

alexlenail opened this issue Feb 2, 2017 · 17 comments

Comments

@alexlenail
Copy link

@alexlenail alexlenail 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
Copy link
Member

@TimKam TimKam 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
Copy link
Member

@tk0miya tk0miya 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
@alexlenail
Copy link
Author

@alexlenail alexlenail commented Feb 3, 2017

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

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

@suhailvs suhailvs 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
Copy link

@ritabratamaiti ritabratamaiti 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
Copy link

@KellyBlack KellyBlack 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
Copy link

@wxianxin wxianxin 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
Copy link

@suhailvs suhailvs 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
Copy link

@songololo songololo 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
* 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
* 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
Copy link

@qwilka qwilka 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
Copy link
Member

@tk0miya tk0miya commented Jan 4, 2019

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

@TimKam
Copy link
Member

@TimKam TimKam commented Jan 4, 2019

I will try to help.

@TimKam TimKam self-assigned this Jan 4, 2019
@jason-huling
Copy link

@jason-huling jason-huling 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
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
Copy link

@H4dr1en H4dr1en 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
Copy link

@H4dr1en H4dr1en 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 pushed a commit to itpp-labs/odoo-test-docs that referenced this issue Apr 30, 2019
robvanholstein added a commit to robvanholstein/IRDAP that referenced this issue May 11, 2019
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
weibullguy added a commit to ReliaQualAssociates/ramstk that referenced this issue Jun 22, 2019
Setup to publish to GitHub pages per
sphinx-doc/sphinx#3382 (comment)
emeryl added a commit to UW-GAC/pie that referenced this issue Dec 28, 2019
ianhi added a commit to ianhi/mpl-interactions that referenced this issue Mar 1, 2020
CiaranWelsh pushed a commit to sys-bio/libOmexMeta that referenced this issue Jul 5, 2020
…thub pages docs with sphinx
hwine added a commit to mozilla/frost that referenced this issue Aug 4, 2020
hwine added a commit to mozilla/frost that referenced this issue Aug 4, 2020
Docs!

* Add rendered docs for gh-pages delivery

Scheme based on
  sphinx-doc/sphinx#3382 (comment)

* Makefile support for gh-pages hosted docs

N.B. we require user to have sphinx installed globally at the moment.
That is somewhat reasonable, as Rust language uses sphinx for
documentation.

If we end up wanting specific sphinx extensions, we'll have to add
those requirements to a (not yet in existence) requirements-dev.txt.
Ambro17 added a commit to Ambro17/slackify that referenced this issue Sep 26, 2020
* 📚 Replace pdoc3 with sphinx docs

* 👀 Add hint for github to ignore kekyll rendering

* 🎨 Remove warning

* 📚 Add redirect to sphinx custom html dump. Reference: sphinx-doc/sphinx#3382

* 🔧

* 🔧 Unignore docs artifacts

* 📚

* 🚀 Update docs target

* 🔧

* 🎨 Style Changes
EricWiener added a commit to EricWiener/bbox-utils that referenced this issue Jan 5, 2021
Followed this response sphinx-doc/sphinx#3382 (comment)
to try to make GitHub pages work
@johnthagen
Copy link

@johnthagen johnthagen commented May 2, 2021

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
Copy link

@Darel13712 Darel13712 commented Sep 2, 2021

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
  1. 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.
  2. Don't forget to setup pages to look at the root of your gh-pages branch for built site.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
14 participants