rackerlabs / docs-cloud-load-balancers Goto Github PK
View Code? Open in Web Editor NEWDeveloper documentation source for Rackspace Cloud Load Balancers API
Home Page: https://developer.rackspace.com/docs/cloud-load-balancers/v1/
Developer documentation source for Rackspace Cloud Load Balancers API
Home Page: https://developer.rackspace.com/docs/cloud-load-balancers/v1/
Below is Nick's email. I found several broken links in this common section.
From: Rackspace Hosting [email protected]
Date: Tuesday, July 5, 2016 at 11:55 AM
To: Nicholas Kuechler [email protected], Jesse Noller [email protected]
Cc: Laura Clymer [email protected], group-laura-clymer [email protected]
Subject: Re: bad link in developer docs
Thanks, Nick! I’ll check this out and get it fixed.
From: Nicholas Kuechler [email protected]
Date: Tuesday, July 5, 2016 at 11:09 AM
To: Jesse Noller [email protected]
Cc: Laura Clymer [email protected], group-laura-clymer [email protected]
Subject: Re: bad link in developer docs
Ah, didn't notice that link.
Thanks!
-Nick
On Jul 5, 2016, at 11:07 AM, Jesse Noller [email protected] wrote:
That would be Laura’s Info dev team under me! CC’ing them
Also note the ‘file an issue’ link in the upper left: https://github.com/rackerlabs/docs-cloud-load-balancers/issues - bugs go straight to the team
On Jul 5, 2016, at 11:03 AM, Nicholas Kuechler [email protected] wrote:
Hey Jesse,
A customer in freenode #rackspace channel noticed a bad link in this section:
In the first blue box, the 'try using Rackspace SDKs' link is a dead link.
I'm not sure what team owns the developer docs page but I knew you're involved in a lot of the developer-related stuff, so I was hoping you could forward this to the docs folks.
Cheers,
Nick
When updating an SSL certificate on SSL Termination the private key field is named "privatekey" whereas when updating an SSL on Certificate Mapping it is instead "privateKey" ( note the capital K on key ). The API seems to be case sensitive and report a 400 error. Is it either possible to update the API to make is not case sensitive or update the documentation to make this clear?
Thanks
Adam
Currently CLB is not entertaining a V2 API and the current documentation for V2 is outdated and should be removed.
We may at some point in the near future reinstate V2 work, but it's likely documentation will be a complete rework.
We should remove the current V2 spec from this repo to clean things up and remove confusion.
Internal docs files are now in https://github.rackspace.com/IX/internal-docs-cloud-load-balancers-1
Describe your documentation issue in the relevant section. Submit product operation or
performance issues to the Rackspace product team at https://feedback.rackspace.com/.
Link to documentation with issue:
https://developer.rackspace.com/docs/cloud-load-balancers/v1/api-reference/throttle-connections/
Report missing information:
Per https://one.rackspace.com/x/1Y5oGg , the Cloud Load Balancer will return a 503 Server Too Busy if it is throttling connections. However, we don't have that anywhere in the docs, and customers assume there's something wrong with the CLB when they see a 503 error.
If we could get the information in the one wiki article into the CLB docs, that would help clear things up for customers.
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.
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.
https:\\developer.rackspace.com\docs\<updated-path>
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 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.
Document with the issue: https://github.com/rackerlabs/docs-cloud-load-balancers/blob/master/api-docs/cloud-load-balancers-v1/api-reference/methods/post-add-node-v1.0-account-loadbalancers-loadbalancerid-nodes.rst
Report incorrect information:
This document states that to add a node to a load balancer,
this operation does not accept a request body.
This is incorrect; the operation requires a request body and the very next section in the docs have an example request body.
Per Jorge Miramontes, the v2 Admin Guide should be migrated but is a low priority item for the Cloud Load Balancer team.
From Margaret:
If migration is required, please update this issue to reflect required work:
For the API Sphinx docs, we're standardizing on a folder structure like this:
├── api-docs
│ ├── Makefile
│ ├── _build
│ │ └── deconst-single
│ ├── _deconst.json
│ ├── api-operations
│ │ ├── access-lists.rst
│ │ ├── algorithms.rst
│ │ ├── allowed-domains.rst
Load balancers has the Sphinx source project three levels down:
├── rst
│ └── dev-guide
│ ├── common-gs
│ │ ├── auth-using-curl.rst
│ │ ├── get-credentials.rst
│ │ ├── how-to-use-curl.rst
│ │ ├── images
│ │ │ └── show-api-key-control-panel.png
│ │ ├── samples
│ │ │ ├── auth-req-curl.rst
│ │ │ ├── auth-resp-json.rst
│ │ │ ├── auth-token-object.rst
│ │ │ └── service-catalog-endpoint.rst
│ │ └── using-env-variables.rst
│ ├── getting-started
│ │ ├── authenticate.rst
│ │ ├── examples
│ │ │ ├── add-node.rst
│ │ │ ├── copy-paste-curl-terminal.rst
│ │ │ ├── create-cloud-servers-to-lb.rst
│ │ │ ├── create-load-balancer.r
This might be accounting for the fact that LB still has internal doc book content in the src directory.
When that content is converted, we should adjust the directory to match the other API doc source repos.
Build and deploy v2 docs.
Kelly edited the contributor collateral, and we added a CONTRIBUTING.md so that users get the link to contributor instructions when working in the repo.
Using [Cloud Identity](https://github.com/rackerlabs/docs-cloud-identity] as a model, update the info for contributors:
Update all links and naming to match product.
The "Building from source" link at the bottom of the Contributing doc does not work (404). I'm not sure which file in the tools directory of the docs-rackspace repo the link is supposed to point to.
May need to remove note at end of Configure environment variables (Note is true for Cloud Queues, but I don't think it's true for Cloud LBs.)
The attached Word doc has my suggested edits for the migrated release notes. Please let me know if you have any questions. Thanks!
Describe your documentation issue in the relevant section.
Link to documentation with issue:
https://docs.rackspace.com/docs/cloud-load-balancers/v1/api-reference/ciphers/
https://github.com/rackerlabs/docs-cloud-load-balancers/blame/master/api-docs/cloud-load-balancers-v1/api-reference/ciphers.rst#L44-L62
Report editorial or format problem:
Report incorrect information:
Report missing information:
Table bullets are missing in FireFox and Chrome.
Documentation feedback:
Hello admins,
The Information Development Team is migrating all documentation repositories published using Deconst to a new publishing platform stack.
This change is to improve functionality, build times, and longevity of the platform.
Things that won't change:
Changes to expect:
The migration has already started and we are unable to provide the exact date that this repo is to be migrated.
If you have questions or concerns please reach out to myself or Robb Romans.
Thanks, William Loy
From: Rackspace Hosting [email protected]
Date: Thursday, August 18, 2016 at 4:56 PM
To: Cody Somerville [email protected], Jens Jorritsma [email protected]
Cc: Carlos Garza [email protected], Adam Harwell [email protected], Peter Lubbs [email protected], Jorge Miramontes [email protected], Rackspace Hosting [email protected]
Subject: Re: August release of CLB 1.0, v1.25.33
Thanks, Cody.
I’ll update the docs as you note below. Please let me know when the release happens and I’ll publish the doc update externally.
Catherine
From: Cody Somerville [email protected]
Date: Thursday, August 18, 2016 at 4:33 PM
To: Jens Jorritsma [email protected], Rackspace Hosting [email protected]
Cc: Carlos Garza [email protected], Adam Harwell [email protected], Peter Lubbs [email protected], Jorge Miramontes [email protected]
Subject: August release of CLB 1.0, v1.25.33
Hi Jens, and Catherine,
Heads up that we’re hoping to perform a CLB 1.0 release next week.
Jens: Can you file the necessary paperwork/tickets for fast track change deploy?
Catherine: Release is bug fix only so does not require documentation changes beyond updated changelog.
Here are the relevant details:
The version number for the August release is 1.25.33.
The changelog for the August release is as follows:
Fixed bug that caused incorrect status to be returned for nodes under certain circumstances when added in condition DRAINING.
Best regards,
Cody
Use text noted in getting-started-QE.md
See QE checklist first item - can use Cloud Queues as model.
Also, to avoid merge conflicts and lots of new files checked in every time.
Update .gitignore specification:
_build/* >> api-docs/_build/*
For PRs, the preview link for v1 internal docs is opening the v2 EA external docs (that were never published externally)
From https://pages.github.rackspace.com/IX/internal-docs-landing-page/ the link for the CLB internal docs does open https://pages.github.rackspace.com/IX/internal-docs-cloud-load-balancers-1/latest/ but there is a v2.0 in the left side of at the top of the page that opens - text in the right does indicate it's v1.0 internal docs though.
Link to documentation with issue:
In PRs, links in preview for internal v1 docs
Report editorial or format problem:
Report incorrect information:
Report missing information:
Documentation feedback:
Use the following checklist to verify the API guide refactoring for Load Balancers, v1. 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.
conf.py
to make sure it has the updates from theUse 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.
conf.py
to make sure it has the updates from theWe'd appreciate your review and feedback on the API Guide prototype to refactor the content architecture and navigation for the Public Cloud API documentation.
Provide any feedback or suggestions for improvement in this issue by Friday, June 17
Thanks for your help!
This issue is a child of the IA - WS issue #58.
See that issue for additional information.
Two Parts!
cloud-load-balancers#update-node
This paragraph in the header uses different terminology than the rest of the doc.
At least one of the optional attributes is required for the Modify Nodes request. (emphasis mine)
"Modify Nodes" appears only once; Update Node appears 4 times. I propose changing the single instance of "modify nodes" to read "update node".
'update-node' does require a request body. The header mentions this, but the 'update-node' section states that the "operation does not accept a request body." This is similar to #152 (fixed with #155). Maybe we copy/paste the same table which lists optional and required attributes/parameters.
Occurences in V1 and V2
It should normally be on the left side of the screen right after the submit an issue link.
See https://developer.rackspace.com/docs/cloud-servers/v2/developer-guide/#document-index for an example
Use case H1 topics use imperative, H2 topics use gerund, for example:
Manage queues and process messages
Creating a queue
Posting messages
etc
per email from Jorge Miramontes on 7/27/2016.
(Getting Started Guide already edited).
Describe your documentation issue in the relevant section.
The table entitled "Table. Required and Optional Attributes for Monitor HTTP and HTTPS" is repeated twice, once with formatting and once without.
The content between the two repeating tables appears inconsistent as well.
The Attribute "bodyRegex" is OPTIONAL; please use the table that has bodyRegex's "Required" column set to "No""
Link to documentation with issue:
https://developer.rackspace.com/docs/cloud-load-balancers/v1/api-reference/monitors/
In Authentication section, above the Example: Authentication response add the following:
.. note::
For detailed information about the authentication response, see the
:rax-devdocs:annotated authentication request and response<cloud-identity/v2/developer-guide/#document-authentication-info/sample-auth-req-response>
in the Rackspace Cloud API documentation.
To remove the link to the gsg on docs.rackspace.com
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.
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.
====
Test
====
=
~
-
^
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:
Note: Don't worry about the line length in code samples or tables for now.
conf.py
)## -- General configuration
line with the first 32 lines fromconf.py
in the API Guide template.deconst-serial
to build chunked html.builder = 'deconst-serial'
#builder = 'deconst-single
extlinks
library matches the one in conf.py
template.sphinx-rtd-template
to improve template for local builds.conf.py
template.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.
When you refactor the content in the overview
source files, you relocate the content and delete the overview
folder and files.
additional-resources.rst
,service-updates.rst
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.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.overview
folder.index.rst
toctree directive:
overview/index.rst
.additional-resources
and service-updates
after the release-notes
fileAfter 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
For the Getting Started section, use the following instructions to refactor the common content and the product-specific Getting Started content.
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:
auth-using-curl.rst
to move everything up one level.get-credentials.rst
topic at the H2 level.concepts.rst
file from the root directory to the getting-started
folder.authentication.rst
to append Identity endpoint information at end of last paragraph. See authentication template.send-request-ovw.rst
to change intro sentence to refer to section andindex.rst
(See template.)
getting-started.rst
to thegetting-started/index.rst
.toctree
specification:get-credentials-include
file at the top of the list.prerequisites
topic.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.
The Developer Guide refactoring moves the content from the Developer Guide introduction to the main index.rst
file.
index.rst
updates:
index.rst
intro before the paragraph with links to the sections of the API documentation. See root index.rst template.developer-guide
developer-guide.rst
file from the root directoryAfter 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.
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.
index.rst
heading level to=======================
General API information
=======================
general-api-info/index.rst
to append a reference to the Getting Started authentication section. (See General API info index.rst #template.)general-api-info
directory.service-access-endpoints.rst
to service-access.rst
and match content to template version.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.
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.
api-operations
folder to api-reference
exclude_pattern
configuration in conf.py
with the new name.api-reference/index.rst
to follow templateapi-reference.rst
in the root directory to make sure it doesn't have any additionalapi-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.index.rst
with new path to api-reference/index.rst
.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.
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
.
releases
sub-folder in the release-notes
directory.releases
folder.release-notes/index.rst
to include all release files... include::
directiverelease-notes/index.rst updates: - [x] Change refid to
.._release-notes-collection:. - [x] Update
release-notes/index.rstto include all release files using the
.. include::`` directive. See template.
index.rst
updates
refid
= release-notes-collection
.release-notes/index
exclude_patterns
specification in the Sphinx configuration file conf.py
torelease-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.
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.
release-notes-collection
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:
additional-resources.rst
service-updates.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.
After you complete the refactoring work, complete the following steps to submit the changes for review:
docs-singlepage.html
to user-guide.html
.The 400 and 401 explanations don't seem spaced correctly. Needs a minor text shifting.
Hi Mike --
I committed the index pages for the api-operation resource types. Those topics (protocols.rst, errorpages.rst) need table and note clean-up.
I am working on the Sphinx build issue and will do another check-in soon. The only files that this change will affect are:
conf.py
index.rst
api-operations/api-operations.rst
I am working on the Sphinx build errors and will check in updates shortly
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.