Planet Open Help

The life and work of the open help community
Join our planet

April 20, 2019

Anne Gentle Anne Gentle

Author of Conversation and Community: the Social Web for Documentation. I’m a writing fiend, technical geek, community doc nut, + Content Stacker for OpenStack.

Tips for publishing Python Sphinx with Free Hosting on GitHub Pages

Here’s a new article on the Docs Like Code site, titled “Yes You Can Use GitHub Pages with Python Sphinx.” If you’re familiar with GitHub Pages, you may also know that by default it builds Jekyll sites and uses selectable Jekyll themes. Jekyll itself mostly publishes with Markdown. For fans of Python Sphinx and the ReStructured Text markup language, figuring out how to use Sphinx instead of Jekyll provides more options and flexibility for doc builds.

Here’s an excerpt, and you can read more in the full article.

Make sure you can still build Sphinx locally for reviews
Here’s another pro tip I found while browsing Issues in the Sphinx repository itself. Since you want to keep the source and output separate, but still be able to both publish on GitHub Pages and preview builds locally, you can add an option to your Makefile to do both.

Docs Like Code website
Mac keyboardFlickr: mleung311 https://flic.kr/p/fqJJbW

by annegentle on April 20, 2019 08:44 PM

Subscriptions

  • Anne GentleAnne Gentle Author of Conversation and Community: the Social Web for Documentation. I’m a writing fiend, technical geek, community doc nut, + Content Stacker for OpenStack.
  • Jim CampbellJim Campbell HRIS admin to the stars, and documentation writer for needy open-source projects. As a Chicagoan, I also know enough to not put ketchup on a hot dog.
  • Lana BrindleyLana Brindley Writes too much, reads too much, talks too much, thinks too much, drinks too much. Generally superlative.
  • Shaun McCanceShaun McCance GNOME documentation team lead. Programmer. Technical writer. XML expert. Community leader. Free software enthusiast.