These guidelines provide the general process for maintaining source code that
builds the Rackspace Federation developer documentation.
- Project description
- Updating and adding content
- Using writing guidelines
- Submitting your content
- Previewing changes
This project is developed and built by using the Python Sphinx documentation generator. Content is written in reStructuredText, which is the markup syntax and parser component of Python Docutils.
Source files for the Sphinx documentation project are in the doc
directory. Following are the key files that define project and content
architecture:
| Content | File |
|---|---|
| Index page for the main content structure | index.rst |
| Common front information | common/common-front.rst |
| Overview index | overview/index.rst |
| Installing index | installing/index.rst |
| Getting started index | getting-started/index.rst |
| Using index | using/index.rst |
| Administering index | administering/index.rst |
| Support index | support/index.rst |
| API | api.rst |
| Common back information | common/common-back.rst |
| Sphinx documentation configuration file | conf.py |
| Linux and OS X build script | Makefile |
| Windows build script | make.bat |
| Install requirements for building locally | requirements.txt |
Contributions are submitted, reviewed, and accepted by using GitHub pull requests (PRs), following the GitHub workflow for this repository.
To update existing source files or add new ones, follow the GitHub workflow for this repository.
- Update source files by using the GitHub editor or any plain text editor.
- Format source files with reStructuredText syntax.
- For quick syntax checking, try the Online reStructuredText editor.
When you add or update content, use the writing and style guidelines in the Style guidelines for technical content. Start with the guidelines in the Quickstart section.
When you've completed your changes, submit a PR. Someone on the Information Development team will review your PR.
- Minor updates and corrections get a quick review to ensure that content is error-free and doesn't introduce other issues.
- More complex changes or additions require both technical and editorial review.
Depending on the review feedback, you might be asked to make additional changes.
After content has been reviewed and approved, the updates can be merged to the master branch. The merge triggers the build and deploy process. Typically, new content is available on developer.rackspace.com within a minute or two after it is merged. Larger updates might take a bit longer.
When you submit a PR, the build process creates a preview of your changes in a staging environment. After the build process is complete, a message is displayed in the PR comments with a link to the content in the staging environment.
You can also build the project locally by using the Sphinx documentation generator. For details, see Building from source.