Sphinx on GitHub Pages

[Miguel Villa Floran]

Hello, I was interested in using Sphinx (along with the Sphinx theme Furo) on GitHub pages. I would create a GitHub repo and host the source files of the documentation on the git branch 'main' and build the source files using GitHub actions and commit the build files onto the branch 'gh-pages'. From there I would open the 'gh-pages' branch would be published to the web via GitHub Pages. Has anyone implemented this approach before?

[c.b...@posteo.jp]

Hello Miguel

Am 09.03.2022 03:36 schrieb Miguel Villa Floran:
> GitHub Pages. Has anyone implemented this approach before?

Not on GitHub but on Codeberg (based on Gitea).

Here is the landing page of my repo. On top of the README.md you can see
a link to the "page" directing to the "docs" folder and its
"index.html".
https://codeberg.org/buhtz/sphinx_versuch

[Pradyun Gedam]

Hi there!  Furo’s own documentation is generated this way. You can find the details in the .github/workflows directory. :)

[Dave Dittrich]

That is how I generate my home page: https://davedittrich.github.io/

I use this Makefile from the Sphinx source directory to copy/commit to the GitHub Pages repo before pushing.

# Don't put trailing slash here: add it in rsync
# commands where necessary because its existence means
# something.
GHPAGES:=../davedittrich.github.io
SHELL=/bin/bash

# Implement a date-based version numbering scheme.
SHORT_YEAR=$(shell date +%y)
# Strip leading spaces so math works right
MONTH=$(shell date +%m | sed 's/^0//')
DAY_OF_MONTH=$(shell date +%d|sed 's/^0//')
MINS_PAST_MIDNIGHT=$(shell expr `date +%H` \* 60 + `date +%M`)
MINUTE_IN_MONTH=$(shell echo $$(( ( $(DAY_OF_MONTH) - 1 ) * 24 * 60 + $(MINS_PAST_MIDNIGHT) )) )
DATE_VERSION=$(SHORT_YEAR).$(MONTH).$(MINUTE_IN_MONTH)
VERSION=$(shell cat VERSION)

.PHONY: _help
_help:
@echo VERSION=$(VERSION)
@echo DATE_VERSION=$(DATE_VERSION)
$(MAKE) help

.PHONY: bump
bump:
bumpversion --no-tag patch --current-version $(VERSION) --new-version $(DATE_VERSION)

.PHONY: publish
publish:
$(MAKE) gh-pages-commit
$(MAKE) gh-pages-push

.PHONY: push
push:
git push

source/robots.txt: robots.j2
env bash render_template robots.j2 source/robots.txt

.PHONY: gh-pages
gh-pages:
$(MAKE) -B source/robots.txt
$(MAKE) html
rsync -av \
     --delete \
     --exclude=README.md \
     --exclude=.git \
     --exclude=_downloads \
     --exclude=.nohyde \
     --exclude=.nojekyll \
     -r \
     build/html/ pgpkey.txt nwba redirect $(GHPAGES)
rsync -av \
downloads/ $(GHPAGES)/_downloads/

.PHONY: gh-pages-commit
gh-pages-commit: gh-pages
(cd $(GHPAGES) && git add _downloads/* && git commit -a -m 'Update gh-pages')

.PHONY: gh-pages-push
gh-pages-push:
(cd $(GHPAGES) && git push)

.PHONY: livehtml
livehtml:
sphinx-autobuild -p 0 \
--re-ignore '.*.swp' \
--re-ignore '.*.swx' \
-b html \
$(ALLSPHINXOPTS) \
$(BUILDDIR)/html

--
You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/b767d1481f881c3209a6835fb793bd60%40posteo.de.

--

Dave Dittrich

@davedittrich
dave.d...@gmail.com

https://davedittrich.github.io/

[Shengyu Zhang]

There is alreay an out-of-box actions for publishing Sphinx documentation to gh-pages: https://github.com/sphinx-notes/pages/