rackerlabs/docs-cloud-keep

DEPRECATED: Rackspace Cloud Keep API documentation

DEPRECATED: The Cloud Keep API service is no longer available.

Rackspace Cloud Keep API documentation

This repository contains the source files that generate the following Cloud Keep API documentation:

• Getting started
• Release notes
• API Reference

When you commit changes to the master branch of this repository, the Strider CI/CD build job builds the documentation. Successful builds are deployed to production.

For additional information about Rackspace documentation, see the Documentation Team FAQ.

Support and feedback

We welcome feedback, comments, and bug reports. Follow the contributor guidelines to propose a source file change, or submit a GitHub issue to request an update or provide feedback.

You can also contact the Rackspace documentation team directly for general issues or questions about the content.

docs-cloud-keep's Issues

Strider build

I made the updates to the project to support Strider builds for this repo as described here: rackerlabs/nexus-control#346. The webhook for Strider needs to have the secret added @smashwilson.

Update README and add CONTRIBUTOR.md

Remove Cloud Keep API docs

• Remove from landing page.
• Remove from nexus-control config
• Delete content from deconst datastore

Add link to resource descriptions in API reference sections

Raj Patel noted that the API reference sections don't provide much context about the API objects (Containers, Secrets, and so on). Info is Concepts section. Short term solution -- add links from the API reference sections for each resource (object).

wrong directory specified for opening built docs

See https://github.com/rackerlabs/docs-barbican/blob/master/CONTRIBUTING.md#view-the-html-build-results

Says to "open _build/html/index.html"

However, if you use "make clean singlehtml" then it should read "open _build/singlehtml/index.html"

Add types of algos for create-secret doc

Keep-2151

Review accuracy of info about service endpoints

Not sure the information in the Regionalized service endpoints documents the Cloud Keep endpoints accurately. @sheyman Can you review?

Refactor API Guide

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:
  - [ ] 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.
  - [ ] Remove the link to the Developer Guide section.
  - [ ] 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 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.

• 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:. - [ ] Updaterelease-notes/index.rstto 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.

Make sure to update document change history

Don't forget to add the multi-factor authentication update entry to the document change history.

linky no worky for using deconst client to build RAX branded docs

See https://github.com/rackerlabs/docs-barbican/blob/master/CONTRIBUTING.md#previewing-changes

The link for "instructions for building with the client" takes you to 404 land:

https://github.com/rackerlabs/docs-migration/blob/master/docs/migration-instructions.rst#building-your-project-with-the-local-deconst-client

Unless its something that I don't have access to?

Update index.rst to add links to different parts of book

The Cloud Keep documentation is missing the top-level links to the different parts of the content that other API docs have: https://developer.rackspace.com/docs/cdn/v1/developer-guide/

Add the links to index.rst.

Updates for Cloud Keep LA

• Replace EA topic with LA topic
• Add endpoints for supported regions
• Add LA watermark

Questions: @joesavak

Updates required for Permissions Matrix for RBAC article?

Cloud Keep FAQ for the Support How-To article collection?

Add Cloud Keep as product on How-To site?

How-To articles required?

Add contributor collateral to repos

Using [Cloud Identity](https://github.com/rackerlabs/docs-cloud-identity] as a model, update the info for contributors:

Revise README.md
Add CONTRIBUTING.md
Add GITHUBING.md
Update all links and naming to match product.

Cloud Keep editorial review

@kmsholcomb Submitting Cloud Keep docs for editorial review.

Rename docs-barbican repo

Rename the repo to docs-cloud-keep to match Rackspace product name.

Also requires updates to nexus-control configuration.

QE refactored Cloud Keep content

Refactor API Guide: QE checklist

Use the following checklist to verify that API guide refactoring for each service. If you have questions, open a docs-common issue.

Do the QE check against the PR submitted to the master repo. Ask the person who did the refactoring to make you a collaborator on their fork in case you want to submit a PR to correct something.

When you build the refactored Sphinx project, use the make clean html command to build chunked content.

• Review the Strider build log for errors. Notify author about any issues.
• Check for broken links.
• Verify that navigation matches the API Guide template.
• Check the API reference section to verify that the methods for each resource are in a single topic.
• Check the General API information topics to make sure they match the common content where possible.
• Check the Authentication topic in the Getting started section to make sure it matches the common template.
• Check conf.py to make sure it has the updates from the
  template.
• Verify that you can build locally from source.

Configure Environment Variable

https://developer.rackspace.com/docs/cloud-keep/v1/developer-guide/#configure-environment-variables only applies to CLI. Need to specify that a user using http would have to specify it in http header.

Refactor API Guide: publish and deploy updates

Update the content URL for refactored API documentation

• Fork and clone the nexus-control to your local system.
• Remove developer-guide from the route configured for the content.

  • Update the nexus-control configuration file as shown in the following example:

    Original: "/docs/cloud-load-balancers/v1/": "https://github.com/rackerlabs/docs-cloud-load-balancers/v1/developer-guide",

    Updated:``"/docs/cloud-load-balancers/v1/": "https://github.com/rackerlabs/docs-cloud-load-balancers/v1/",

    Notes:

    The value on the left is the path to deploy content. The value to the right of the : is the unique
    content ID for the Sphinx project. The content ID must match the "contentIDBase" value in the
    _deconst.json file in the documentation source directory. See Configure development and production builds for Sphinx projects.

• Update the deploy URL in the route configuration file to match the one in the nexus-control configuration file.
• Create a redirect rule for the original URL.

  • Edit the rewrites file to add a redirect rule for the original URL as shown in the following example:

      {
         "description": "Redirect load balancers developer-guide URL",
         "from": "^\\/docs\\/cloud-load-balancers\\/v1\\/developer-guide\\/(.*?)",
         "to": "/docs/cloud-load-balancers/v1/$1",
         "rewrite": false,
         "status": 301
     },
    

  • Use a json linter to verify that the JSON syntax is correct.

• Commit the changes, and push to your fork.
• Submit your updates as a PR against the upstream repository. Include a link to the PR containing the refactored documentation source.
• After the PR is merged, verify that the content is deployed to the new URL, for example https:\\developer.rackspace.com\docs\<updated-path>
• Verify that the redirect rule is working by clicking the Developer Guide link on the DRC docs landing page.

Note: Nexus-control changes take longer to deploy than content changes. You can check the nexus-control version information to determine whether the commit has been deployed.

Update the documentation landing page

Update the menu so that it matches the Load Balancers v1 example shown in the following figure:

Important: Don't commit the landing page updates until you have verified that the content has been deployed to the new URL.

Some menus might be slightly different if the product doesn't have an SDK Quickstart, or if it has additional documentation. If you have questions about the menu content or order, open an issue.

• Fork and clone the docs-quickstart repo to your local system.
• Find the menu for the API documentation you are updating.
• Update the title list and href link targets with the information for your documentation.
• Save the file.
• Commit the changes and push to your fork.
• Submit your updates as a PR against the upstream repository. Include a link to the PR containing the refactored documentation source.
  • Check the PR builder preview to make sure the landing page renders correctly with your updates.
  • Request someone to review and merge the PR.