Instructions/resources here:
https://github.com/rackerlabs/docs-common/blob/master/refactor-api-guide.md
and
rackerlabs/docs-common#68
and
https://github.com/rackerlabs/docs-common/tree/master/api-guide-template
Refactor API Guide checklist
Use the following checklist to guide and track the refactoring work for
each Developer Guide. If you have questions, open a docs-common issue.
When you build the refactored Sphinx project, use the make clean html
command to build chunked content. Before you begin refactoring, review restructured text fixes.
Important: If the project contains additional source files or content significantly
different than the template, add a link to the source in Issue #62 in the docs-common repo.
RST coding syntax fixes
Refactoring the API guides gives us a chance to make our RST source files comply with coding best practices. You can make the following changes when you are refactoring, or make the updates in a separate effort. When the changes are complete, check off the list items.
- Wrap all lines to 79 characters.
- Ensure that heading separator lines are the same length as the title
- Use the following symbols for heading separators:
- H1: over and underline
=
- H2:
~
- H3:
-
- H4:
^
Tip: If you are using the Atom editor, you can configure the soft wrap feature to reflow text
to 79 characters with a keybinding:
- Set the line length:
- Click Atom > Preferences > Settings.
- Change the Preferred Line Length to 79.
- Make sure that Soft wrap at Preferred Line length is selected.
- Do not select the Soft wrap selection.
- Reflow text that exceeds 79 characters.
- Select the line or paragraph.
- Click alt+cmd+q to reflow the text. If text is indented or has special formatting,
you have to adjust the text manually.
Note: Don't worry about the line length in code samples or tables for now.
Configuration updates (conf.py
)
After you complete the conf.py
updates, run the Sphinx build (make clean html
) to test that the build still works: make clean html
. Resolve any errors.
Note: If the Sphinx build doesn't run, follow the build from source instructions to install the required dependencies.
Overview updates
When you refactor the content in the overview
source files, you relocate the content and delete the overview
folder and files.
After you complete the overview
updates, run the local Sphinx build. Resolve any errors. Then, run the following command to review the local build output to verify that the API description, Additional resources and Service updates content renders correctly: open _build/html/index.html
Getting started updates
For the Getting Started section, use the following instructions to refactor the common content and the product-specific Getting Started content.
Update common gs-section
The changes made to the common-gs content include the following:
Update Getting Started section
After you complete the Getting Started updates, rebuild the Sphinx project. Resolve any errors. Then, review the local build output to verify that the content renders correcctly and that it matches the Getting started template.
Developer Guide updates
The Developer Guide refactoring moves the content from the Developer Guide introduction to the main index.rst
file.
After you complete the Developer Guide updates, rebuild the Sphinx project. Resolve any errors. Then, preview the local build output to verify that the Developer Guide section was removed.
General API info updates
When you refactor the General API section, the main changes are removing the authentication
topic and adjusting the heading levels.
=======================
General API information
=======================
After you complete the Getting Started updates, rebuild the Sphinx project. Resolve any errors, Then, review the local build output to verify that the content renders correctly and that it matches the General API information template.
API Reference updates
When you refactor the API reference section, the main changes are relocating the api-reference heading to api-reference/index.rst
topic and adjusting the heading levels in the methods section.
After you complete these updates, rebuild the Sphinx project. Resolve any errors. Then, review the local build output to verify that the content renders correctly and that it matches the API Reference API reference template.
Release notes updates
When you refactor the API reference section, the main change is relocating the Release notes heading and introduction to release-notes/index.rst
, moving the release note topics to a sub-folder, and including all release notes topic in index.rst. You also need to add the new release-notes
folder to the exclude_patterns
specification in the Sphinx configuration file, conf.py
.
After you complete the updates, rebuild the Sphinx project. Resolve any errors. Then, review the local build output to verify that the content renders correctly and that it matches the API Guide Release notes template.
Root index.rst updates
Many of the refactoring changes in the root index.rst
file were completed when you refactored earlier section. These instructions provide a summary of the changes so you can verify them.
Product name v# <https://developer.rackspace.com/docs/cloud-load-balancers/v1/>
getting-started/index
general-api-info/index
api-reference/index
release-notes/index
service-updates
additional-resources
copyright
Changes include:
Note: If your project contains additional source files not included in this list, add them to Issue #62 in the docs-common repo. Include them in the content architecture where it makes sense. IA team can review.
Next steps
After you complete the refactor work, submit a PR against your upstream repository and follow the Review instructions.
Copied from https://github.com/rackerlabs/docs-migration/issues/109 on 7/27/2016