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 the 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.
- 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:
^
In the same file, the header levels must be in sequential order. If they aren't, you get the following error when you run the Sphinx build: SEVERE/4) Title level inconsistent.
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)
Tip: To catch errors inline, configure Atom for Python.
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. You'll also need to change some common file names and content to match the common content in the API Guide template. Some of these changes are included in the instructions, but there are too many to document in detail. Be careful when you make these changes, some projects have custom information that differs from other projects.
Important: If you have common files in your source that are not in the template directory or significantly deviate from the template source file, add a link to the Github source for that file to the General API info source file issue. This list will help us review and improve the General API Info content and determine whether it needs to be included in the API template.
=======================
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 refactoring work, complete the following steps to submit the changes for review:
- To change the API documentation template for your project, update the routes.d file in the nexus-control repository to change the template from
docs-singlepage.html to user-guide.html.
- After the nexus-control PR has been merged, submit a PR with your refactoring changes against your upstream repository.
- Follow the review instructions.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent