Upload to Online Website¶

Github¶

This guide explains how to upload your Sphinx documentation to GitHub Pages for hosting your project’s documentation online.

You must have a GitHub repository for your project.
Your Sphinx documentation should be ready and built using the sphinx-build command.
Ensure you have the ghp-import tool installed. If not, you can install it via pip:
```
pip install ghp-import
```

Enable GitHub Pages in Your Repository Settings

Go to your GitHub repository’s settings page. Under the Pages section, select the gh-pages branch as the source for GitHub Pages.

If gh-pages branch does not exist, you can create it by running the following command in your repository directory:
```
git checkout --orphan gh-pages
git reset --hard
git commit --allow-empty -m "Initializing gh-pages branch"
git push origin gh-pages
```
Configure `conf.py` for GitHub Pages

In the conf.py file of your Sphinx project, add the following line to enable the sphinx.ext.githubpages extension:
```
extensions = [
    'sphinx.ext.githubpages',
]
```
This extension ensures that a .nojekyll file is created in the build directory, which prevents GitHub Pages from applying Jekyll processing (important for files with underscores).
Build the Documentation

Next, build your documentation into HTML format by running the following command:
```
sphinx-build -b html source/ build
```
This generates the documentation files in the build/ directory.
Upload the Documentation to GitHub Pages

Once the documentation is built, use ghp-import to push the built files to the gh-pages branch:
```
ghp-import -p -f build/
```
The -p flag automatically pushes to the remote GitHub repository, and the -f flag forces the upload (even if the destination is not empty).

After this, your Sphinx documentation will be live on GitHub Pages!

Page not displaying? Ensure the gh-pages branch is properly configured in the GitHub Pages settings of your repository.
Underscore files not showing? The .nojekyll file generated by sphinx.ext.githubpages should prevent GitHub from blocking those files. If needed, manually check for the existence of .nojekyll in the root of the build/ directory before uploading.