You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@trafficcontrol.apache.org by GitBox <gi...@apache.org> on 2018/12/03 17:13:54 UTC
[GitHub] ocket8888 opened a new pull request #3078: WIP - API documentation
overhaul
ocket8888 opened a new pull request #3078: WIP - API documentation overhaul
URL: https://github.com/apache/trafficcontrol/pull/3078
## What does this PR do?
This PR is an overhaul to the way the API documentation is laid out. It gives each unique request path its own page - but only considers request paths unique if they differ after the `/api/1.x/` portion. Rather than a new page in every minor API version, the docs will use the `versionchanged`, `versionadded`, and `deprecated` reStructuredText directives to indicate changes between minor versions.
Also, each page follows the same, consistent formatting using proper section headings that allow links to specific parts of specific methods on an endpoint to be "link-able" - as well as the (now fully-HTTP wherever possible) request and response sections.
Grouping of endpoints by function is not currently implemented, but will probably be done when I finally get around to fixing up the index page with an explanation of the new layout.
#### Which TC components are affected by this PR?
- [x] Documentation
- [ ] Grove
- [ ] Traffic Analytics
- [ ] Traffic Monitor
- [ ] Traffic Ops
- [ ] Traffic Ops ORT
- [ ] Traffic Portal
- [ ] Traffic Router
- [ ] Traffic Stats
- [ ] Traffic Vault
- [ ] Other _________
## What is the best way to verify this PR?
Build the documentation, and evaluate if the new layout is effective.
## Check all that apply
- [ ] This PR includes tests
- [x] This PR includes documentation updates
- [ ] This PR includes an update to CHANGELOG.md
- [ ] This PR includes all required license headers
- [ ] This PR includes a database migration (ensure that migration sequence is correct)
- [ ] This PR fixes a serious security flaw. Read more: [www.apache.org/security](http://www.apache.org/security/)
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services