These guidelines provide the general process for maintaining source code that builds the Rackspace Cloud Images developer documentation.
- Project description
- Updating and adding content
- General style guidelines
- Submitting your content
- Previewing changes
##Project description
This project is developed and built using the Python Sphinx documentation generator. Content is written in reStructuredText, the markup syntax and parser component of Python Docutils.
Source files for the Sphinx documentation project are in the api-docs directory. Here are the key files that
define the Sphinx project and content architecture for the documentation:
| Content | File |
|---|---|
| Index page for the main content structure | index.rst |
| About the API index | overview/index.rst |
| Getting Started introduction | getting-started.rst |
| Developer Guide introduction | developer-guide.rst |
| Concepts section | concepts.rst |
| General API information index | general-api-info/index.rst |
| API Reference introduction | api-reference.rst |
| API Reference index | api-operations/index.rst |
| API operations methods, including code samples | api-operations/methods |
| Release notes | release-notes.rst |
| Linux and OS X build script | Makefile |
| Windows build script | make.bat |
| Requirements file to support local builds | requirements.txt |
Contributions are submitted, reviewed, and accepted by using GitHub pull requests, 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 following general style guidelines, which are described in detail in Style guidelines for technical content:
- Use sentence-style capitalization for titles and headings
- Use consistent text formatting
- Write clear and consistent code examples
- Use active voice
- Use present tense
- Write to the user by using second person and imperative mood
- Write clear and consistent step text
- Clarify pronouns such as it, this, there, and that
- Clarify gerunds and participles
- Use consistent terminology
When you've completed your changes, submit a pull request. 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 pull request, the Strider build process creates a preview of your changes in a staging
environment. After the build process completes, the following message displays in the pull request comments
with a link to the content: Your content preview is now ready.
You can also build the project locally using the Sphinx documentation generator. For details, see Building from source.