Skip to content

maltfield/rtd-github-pages

master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 

docs_pages_workflow

Continuous Documentation: Hosting Read the Docs on GitHub Pages

This repo is a fork-ready base for your project's documentation. It lets you host a sphinx-generated site (with the Read the Docs theme) on GitHub Pages using GitHub Actions.

Continuous Documentation with Read the Docs on GitHub Pages using GitHub Actions

For more information, see this article:

How to use this repo

  1. Fork this repo
  2. On your forked repo, go to the "Actions" tab and click "I understand my workflows, go ahead and enable them" to enable GitHub workflows
  3. On your forked repo, go to the "Settings" tab. Under "GitHub Pages" choose 'gh-pages branch' under "Source"
  4. Make a small change to docs/index.rst
  5. git commit and git push something to trigger your site to be built

Every time you push to github.com on master, github will automatically spin up a container in their cloud to update your documentation.

After you begin to edit the contents of the site, you'll probably also want to customize the following files:

  1. docs/conf.py
  2. The python files in src/
  3. Other .rst files in docs/ as needed

For more details on how this works, see Continuous Documentation: Hosting Read the Docs on GitHub Pages

Demo

The GitHub-Pages-hosted "Hello World" example site built by this repo can be viewed here:

In the wild

The following Githb-Pages-hosted Read the Docs sites have been created by cloning this repo:

Local Iteration

As shown above, you can simply push your changes to GitHub to update your sphinx documentation website.

However, you can also build the site locally on your computer for faster iteration.

Linux

To build the site on Debian Linux, first download some dependencies

sudo apt-get update
sudo apt-get -y install git firefox-esr python3-git python3-sphinx python3-sphinx-rtd-theme

Change into the docs directory of this repo and build the sphinx site with make

cd rtd-github-pages/docs/
make clean
make html

You can view the site (built into the _build/html/ directory) using firefox

firefox-esr _build/html/index.html

License

The contents of this repo are dual-licensed. All code is GPLv3 and all other content is CC-BY-SA.

About

Fork-ready base for your project's documentation using Sphinx + Read the Docs on GitHub Pages

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages