How to host Sphinx documentation on GitHub Pages?

Question

I recently wrote a Python package and generated some documentation using Sphinx. I added the documentation to the project's GitHub repo and would now like to host the static pages. I read online that you can use GitHub Pages to do this.

As such, I made sure to enable GitHub Pages for the public repo and select the docs folder for the root directory.

Currently, I am running into a:

404 Files not Found Error

every time I try to access the projects link.

The current hierarchy of the docs directory is structured as:

- docs
   - source
       - index.rst
       - installation.rst
       - conf.py
       - examples.rst
   - Makefile

I have read a few things online such as this which seems to imply that a problem could occur if you have sub directories (ie. for me, in this case, the problem could be that I have a separate source directory in the docs directory and not just all of the files in the same directory). I think this may be the problem, the only part is I am unsure how to solve this.

Would I have to select all of the files in the source subdirectory and move them to the docs directory with the Makefile? How would I do that? This must be the structure that I am using to track them on Git, so perhaps I would have to change how Git is tracking them?

Any links to resources or examples would be greatly appreciated.

Edit: I am looking at this repo in particular where it seems that the docs are both hosted on GitHub pages and are uploaded to the repo in a .rst file format. Does this maybe have something to do with Jekyll or something?

Updated:

Edit 2: I ended up removing the .rst files from the repo (untracking them from git) and pushed the .html files in the build directory. Since GitHub Pages requires docs to be in the root /docs directory I just copied the .html files into the /docs root folder in the repo. However, the problem that I am running into is that now the theme is not building correctly and I am only getting a skeletal version of the index.html build.

I have determined that this likely has something to do with the _static files not being included or some other files necessary for the theme to build correctly. My question is, what is the directory structure of this project supposed to look like?

Do we for example have:

/docs
   _static
   index.html

What are the files that we need to include for the Sphinx Documentation to build correctly and what level should each of the files/folders be in the /docs root directory?

In other words, I am getting the theme related issue detailed in this blog post. I tried simply moving the _static folder up the directory to the level with the index.html file, but this did not seem to solve the issue.

user_11182 · Answer

Since you pointed out the repo you were looking at, it is possible now to tell how that author makes everything working.

The actual doc generation/deployment workflow is in CircleCI config, https://github.com/amueller/dabl/blob/main/.circleci/config.yml

It simply does the following,

Use build_doc.sh to generate HTML pages and other artifacts.
Use push_doc.sh to copy all artifacts to a GitHub Pages enabled repo, https://github.com/amueller/amueller.github.io

So like I commented, this author only hosts HTML pages and other artifacts generated by Sphinx (as that's what GitHub Pages desires), but not reStructuredText source files.

How to host Sphinx documentation on GitHub Pages?

Updated:

1 Answers