This system uses the Python Sphinx tool for structure & building as part of the static build process. Included is a Makefile & make.bat file for cross platform building (for development/contribution).
Layout:
- _static: static assets unique to the documentation; this may include js, css, images, etc.
- _templates: custom html templates
- conf.py: Configuration, no touchy.
- index.rst: Main index / landing page for the docs
- make.bat: windows build script
- Makefile: linux/osx build
You will need Sphinx installed to build - however to contribute, all you need is a basic understanding of the project layout and Restructured Text. Here is an excellent ReST primer.
Once you're all set up: in order to build run:
make html
You will see the build output and the static files will be dropped in:
_build/html
On OS/X you can run:
open _build/html/index.html
To pop open the doc index and preview.
Here's a brief description of the document writing workflow:
- Fork and then clone the repo (https://github.com/rackerlabs/docs-core-infra-user-guide)
- git remote add upstream https://github.com/rackerlabs/docs-core-infra-user-guide.git
- git pull upstream master
- Create a git branch named after the topic you are going to write about
- Follow the basic structure and ReST conventions present in other existing .rst files
- Run Sphinx (as explained above)
- If no errors, git commit[1], then git push origin branch-name
- Submit PR from your branch, to upstream master
[1] We're not committing and pushing the output HTML files. We're only going to commit and push the .rst files. The static pages will then be built, rendered and deployed automatically by the CI.