Do you write documentation with the Sphinx tool chain? Do you want to encourage more people to write Sphinx documentation in a distributed organization, but worry about maintaining compatible workflows? Introducing sphinx-docs-opinionated-quickstart, a template repository with an opinionated configuration of ReStructuredText documentation with Travis CI testing and readthedocs.org publishing.
I created this for the RIT Linux User’s Group (a.k.a. RITlug). RITlug welcomes student-led projects for members to work on together. RITlug executive board members want to better encourage students to share and join projects for collaboration with the community (in the spirit of FOSS). To do this, the executive board members will create and offer both a template website and template documentation tools to introduce students to project development process. Then, students are better able to sustain a more diverse community around their projects.
“Start writing ReStructuredText already!”
The philosophy with this small project is: “Start writing ReStructuredText already!” I use Sphinx with ReadTheDocs as a deployment option across different organizations. I want a common base to later customize for a specific project’s needs.
The whole point of this project is to save time kicking off a new project’s recently-established documentation effort.
Sphinx Travis CI testing configuration included
Complex documentation tool chains need simple validation of successful builds. This avoids long periods where documentation may not build and the public docs are out of date. It also better engages core contributors to monitor and take care of their documentation.
A Travis CI configuration is included. Fork this repository and enable the repo on travis-ci.org to start running builds.
Add a star on GitHub
Does this sound helpful? Check it out and add a star at jwflory/sphinx-docs-opinionated-quickstart. The project is licensed under the BSD 3-Clause License; feel free to fork it and form your own opinions too.
Photo by Jānis Skribāns on Unsplash.
One comment