feat(deprecated): Show a message for deprecated methods

This shows a general deprecation warning for methods that are deprecated by GitHub, and a slightly more informational warning for methods that have been renamed by Octokit. This adds a new field called `afterId` to the `return` field in the `OctokitApiMethod` type, which is used for linking to the renamed method in the documentation.
octokit · Oct 4, 2019 · 453ebcc · 453ebcc
1 parent 831bb65
commit 453ebcc
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 1 deletion.
diff --git a/docs/plugins/gatsby-source-octokit-routes/gatsby-node.js b/docs/plugins/gatsby-source-octokit-routes/gatsby-node.js
@@ -26,10 +26,16 @@ exports.sourceNodes = async ({ actions }) => {
     const example = `octokit.${endpoint.scope}.${_.camelCase(
       endpoint.id
     )}(${paramsString})`;
+    let renamedId;
+
+    if (endpoint.renamed) {
+      renamedId = `octokit-routes-${endpoint.scope}-${_.kebabCase(endpoint.renamed.after)}`
+    }
     const method = {
       ...endpoint,
       id: endpointId,
-      example
+      example,
+      renamed: endpoint.renamed ? {...endpoint.renamed, afterId: renamedId } : undefined,
     };
 
     createNode({
@@ -38,6 +44,7 @@ exports.sourceNodes = async ({ actions }) => {
       children: [],
       id: endpointId,
       example,
+      renamed: endpoint.renamed ? {...endpoint.renamed, afterId: renamedId } : undefined,
       internal: {
         description: `${endpoint.name} Method`,
         contentDigest: endpointId,

diff --git a/docs/src/components/api.module.css b/docs/src/components/api.module.css
@@ -146,6 +146,13 @@ main h2:first-child {
   font-weight: bold;
 }
 
+.deprecated {
+  background-color: #ffe7e8;
+  padding: 1.25rem;
+  border-radius: 0.25rem;
+  margin-bottom: 1rem;
+}
+
 /* Hide the navigation on small screens, until the toggle button is pressed */
 @media (max-width: 55em) {
   /* --wide-enough-for-two-columns */

diff --git a/docs/src/components/endpoint.js b/docs/src/components/endpoint.js
@@ -41,12 +41,29 @@ export default class EndPoint extends Component {
 
   render() {
     const method = this.props.method;
+    if (method.renamed) console.log(method);
     return (
       <React.Fragment>
         <h3 id={method.id} ref={this.headlineRef}>
           {method.name}
         </h3>
 
+        {method.isDeprecated && (
+          <aside className={apiStyles.deprecated}>
+            This method is deprecated.
+          </aside>
+        )}
+
+        {method.renamed && (
+          <aside className={apiStyles.deprecated}>
+            <div>
+              <strong>Deprecated</strong>
+            </div>
+            <span>
+              This method has been renamed from {method.renamed.before} to <a href={`#${method.renamed.afterId}`}>{method.renamed.after}</a>.
+            </span>
+          </aside>
+        )}
         <div dangerouslySetInnerHTML={{ __html: marked(method.description) }} />
 
         <div className="gatsby-highlight" data-language="js">

diff --git a/docs/src/pages/index.js b/docs/src/pages/index.js
@@ -43,11 +43,18 @@ export const query = graphql`
             description
             example
             documentationUrl
+            isDeprecated
+            scope
             parameters {
               name
               required
               description
             }
+            renamed {
+              before
+              after
+              afterId
+            }
           }
         }
       }