Refactor API Guide

[cyrichardson]

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

    ====
    Test
    ====

• 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)

• Replace everything above the ## -- General configuration line with the first 32 lines from
  the conf.py in the API Guide template.
• Change deconst builder configuration to deconst-serial to build chunked html.
  builder = 'deconst-serial'
#builder = 'deconst-single
• Add the spelling checker extension after the extension modules configuration.
• Ensure that extlinks library matches the one in conf.py template.
• Add sphinx-rtd-template to improve template for local builds.
• Add requirements.txt to the root directory to support local builds
• Update titles to remove "Developer Guide". Follow title pattern in conf.py template.
• Verify that configuration settings match those in the conf.py for the API Guide template.
• Check conf.py syntax with pep8. Fix errors.

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.

• Move the following files to the root directory of the Sphinx project: additional-resources.rst,service-updates.rst
• Copy the About API description from overview/index.rst to the beginning of the main index.rst file so that the API description is the first information in the API Guide.
• Move any other files in the overview folder to the root directory, and either integrate the content into another topic, or add the file in the index.rst toctree where it makes sense.
• Delete the overview folder.
• Update the index.rst toctree directive:
  • Delete overview/index.rst.
  • Add additional-resources and service-updates after the release-notes file
    and before the copyright as shown in the index.rst template.

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

• Copy the common-gs folder with the [API Guide template files].(https://github.com/rackerlabs/docs-common/tree/master/api-guide-template/common-gs)

• View the diff of the new content against your existing content.

  If you have any content that's not included in the common content, determine whether it
  needs to be added to the template. If not, then put the content in a different location so
  that the common content is the same across all API Guides. If necessary, open a
  docs-common issue issue
  to update the template or determine how to handle the custom content. All common-gs
  content must be the same.

The changes made to the common-gs content include the following:

• Adjust heading levels in auth-using-curl.rst to move everything up one level.
• Update get-credentials to move heading up a level and remove Cloud Control Panel login info.
• How-to-use-curl minor edits and add Windows cURL info.
• Wrap all lines at 79 characters and remove trailing spaces.
• Miscellaneous editorial improvements.

Update Getting Started section

• Add the get-credentials-include.rst file to the getting-started folder. This file embeds the common get-credentials.rst topic at the H2 level.
• Move concepts.rst file from the root directory to the getting-started folder.
• Update authentication.rst to append Identity endpoint information at end of last paragraph. See authentication template.
• Update send-request-ovw.rst to change intro sentence to refer to section and
  remove link definition for Cloud Control panel. See Send API request template.
• Update index.rst (See template.)
  • Copy the heading and opening paragraph from getting-started.rst to the
    top of getting-started/index.rst.
  • Remove bold format from heading.
  • Add the prerequisite information after the opening paragraph following the getting-started topic template
  • Update toctree specification:
    * Add get-credentials-include file at the top of the list.
    * Remove prerequisites topic.
    * Add concepts.rst after authentication.rst topic.

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.

• index.rst updates:
  - [x] Copy Developer Guide intro about audience and prerequisite knowledge to root index.rst intro before the paragraph with links to the sections of the API documentation. See root index.rst template.
  - [x] Remove the link to the Developer Guide section.
  - [x] Update the toctree specification to remove developer-guide
• Delete the developer-guide.rst file from the root directory

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.

• Change index.rst heading level to

=======================
General API information
=======================

• Update general-api-info/index.rstto append a reference to the Getting Started authentication section. (See General API info index.rst #template.)
• Update the toctree directive to remove the filename for the authentication topic.
• Delete the authentication source file from the general-api-info directory.
• Change headings in sub-topics to H1 and H2 (~~~~~) per template.
• Rename service-access-endpoints.rst to service-access.rst and match content to template version.
• Compare General API Information source files to the source in the API template directory, and update to match common content where possible.

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.

• Rename api-operations folder to api-reference
• Update the exclude_pattern configuration in conf.py with the new name.
• Update api-reference/index.rst to follow template
• Check api-reference.rst in the root directory to make sure it doesn't have any additional
  information not included in the updated api-reference/index.rst file. If no extra content, delete the file. If additional content is included and still needed, move it to the index.rst file.
• Update root index.rst with new path to api-reference/index.rst.
• Change api resource topic heading levels to h1 (====).
• Change api method heading levels to h2 (~~~~~~~~~).
• Change request and response heading levels to h3 (-------).

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 Release notes 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.

• Move release-notes.rst to release-notes folder and rename to index.rst.
• Set up all release note content to render in a single topic.
• Create a releases sub-folder in the release-notes directory.
• Move individual release notes files into the releases folder.
• Update release-notes/index.rst to include all release files.
  Use the .. include:: directive
• ``release-notes/index.rst updates:
• Change refid to .._release-notes-collection:.
• Update release-notes/index.rst to include all release files
  using the .. include:: directive. See template.
• Remove bold format from title.
• Main index.rst updates
  • Update link to release note section to use new
    refid = release-notes-collection.
  • Update toctree specification with path to release-notes/index
• Update the exclude_patterns specification in the Sphinx configuration file conf.py to
  add the release-notes/releases pathr.

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.

• Ensure the first paragraph provides information about audience and prerequisite knowledge like the root index.rst template.
• Update the links to API Guide sections
  • Remove Developer-Guide
  • Change release-notes ref ID to release-notes-collection
• Update files in toctree directive to follow this pattern:

   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:

• Add the following file names:
  • additional-resources.rst
  • service-updates.rst
• Delete the following file names:
  • getting-started.rst topic
  • prerequisites-for-using-api.rst
  • concepts.rst
  • developer-guide.rst
  • api-reference.rst

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:

1. 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.
2. After the nexus-control PR has been merged, submit a PR with your refactoring changes against your upstream repository.
3. Follow the review instructions.