Add API-reference subentries to sidenav (#277)

* Use lang specific redirects + catch all

* Another redirect-rule variant trial

* All languages covered

* Make sidenav API entries: use proper path

* Shortcode tweak

* Redirects cleanup

content/docs/languages/android/_index.md

@@ -1,9 +1,10 @@
 ---
 title: Android Java
+api_path: grpc-java/javadoc
 ---
 
 These language-specific pages are available:
 
 - [Quick start](quickstart)
 - [Basics tutorial](basics)
-- [API reference](https://grpc.github.io/grpc-java/javadoc)
+- [API reference](api/{{< param api_path >}})

content/docs/languages/android/api.md

@@ -0,0 +1,7 @@
+---
+title: API reference
+short: API
+path: grpc-java/javadoc
+weight: 90
+# Note: this is a placeholder page. The URL to this page redirects elsewhere.
+---

content/docs/languages/cpp/_index.md

@@ -7,6 +7,4 @@ These language-specific pages are available:
 - [Quick start](quickstart)
 - [Basics tutorial](basics)
 - [Asynchronous-API tutorial](async)
-- API reference:
+- [API reference](api)
-  - [gRPC C++](https://grpc.github.io/grpc/cpp)
-  - [gRPC core](https://grpc.github.io/grpc/core)

content/docs/languages/cpp/api.md

@@ -0,0 +1,6 @@
+---
+title: API reference
+short: API
+weight: 90
+# Note: this is a placeholder page. The URL to this page redirects elsewhere.
+---

content/docs/languages/cpp/async.md

@@ -1,5 +1,7 @@
 ---
 title: Asynchronous-API Tutorial
+short: Async-API Tutorial
+weight: 60
 ---
 
 This tutorial shows you how to write a simple server and client in C++ using

content/docs/languages/csharp/_index.md

@@ -1,5 +1,6 @@
 ---
 title: C# / .NET
+api_path: api/Grpc.Core
 ---
 
 There are two official implementations of gRPC for C#. The original [gRPC
@@ -7,7 +8,7 @@ core-library][core-library] implementation is covered here:
 
 - [Quick start](quickstart)
 - [Basics tutorial](basics)
-- [API reference](https://grpc.github.io/grpc/csharp/api/Grpc.Core)
+- [API reference](api/{{< param api_path >}})
 
 For details concerning the newer gRPC for .NET implementation, see [gRPC for
 .NET](dotnet).

content/docs/languages/csharp/api.md

@@ -0,0 +1,6 @@
+---
+title: API reference
+short: API
+weight: 90
+# Note: this is a placeholder page. The URL to this page redirects elsewhere.
+---

content/docs/languages/csharp/dotnet.md

@@ -1,5 +1,6 @@
 ---
 title: gRPC for .NET
+weight: 60
 ---
 
 The following pages cover the C# implementation of gRPC for .NET
@@ -7,7 +8,7 @@ The following pages cover the C# implementation of gRPC for .NET
 
 - [Introduction to gRPC on .NET Core](https://docs.microsoft.com/aspnet/core/grpc)
 - [Tutorial: Create a gRPC client and server in ASP.NET Core][tutorial]
-- [API reference](https://grpc.github.io/grpc/csharp-dotnet/api/Grpc.Core)
+- [API reference](../api/grpc/csharp-dotnet/api/Grpc.Core)
 
 Several sample applications are available from the [examples][] folder in the
 [grpc-dotnet][] repository.

content/docs/languages/dart/_index.md

@@ -1,9 +1,10 @@
 ---
 title: Dart
+api_path: pub.dev/documentation/grpc?ext=1
 ---
 
 These language-specific pages are available:
 
 - [Quick start](quickstart)
 - [Basics tutorial](basics)
-- [API reference](https://pub.dev/documentation/grpc)
+- [API reference](api/{{< param api_path >}})

content/docs/languages/dart/api.md

@@ -0,0 +1,6 @@
+---
+title: API reference
+short: API
+weight: 90
+# Note: this is a placeholder page. The URL to this page redirects elsewhere.
+---

content/docs/languages/go/_index.md

@@ -1,5 +1,6 @@
 ---
 title: Go
+api_path: pkg.go.dev/google.golang.org/grpc?ext=1
 ---
 
 These language-specific pages are available:
@@ -7,4 +8,4 @@ These language-specific pages are available:
 - [Quick start](quickstart)
 - [Basics tutorial](basics)
 - [Generated-code reference](generated-code)
-- [API reference](https://godoc.org/google.golang.org/grpc)
+- [API reference](api/{{< param api_path >}})

content/docs/languages/go/api.md

@@ -0,0 +1,6 @@
+---
+title: API reference
+short: API
+weight: 90
+# Note: this is a placeholder page. The URL to this page redirects elsewhere.
+---

content/docs/languages/go/generated-code.md

@@ -1,6 +1,7 @@
 ---
 title: Go Generated-code Reference
 short: Generated Code
+weight: 80
 ---
 
 This page describes the code generated with the [grpc plugin](https://godoc.org/github.com/golang/protobuf/protoc-gen-go/grpc) to `protoc-gen-go`

content/docs/languages/java/_index.md

@@ -1,5 +1,6 @@
 ---
 title: Java
+api_path: grpc-java/javadoc
 ---
 
 These language-specific pages are available:
@@ -7,4 +8,4 @@ These language-specific pages are available:
 - [Quick start](quickstart)
 - [Basics tutorial](basics)
 - [Generated-code reference](generated-code)
-- [API reference](https://grpc.github.io/grpc-java/javadoc)
+- [API reference](api/{{< param api_path >}})

content/docs/languages/java/api.md

@@ -0,0 +1,6 @@
+---
+title: API reference
+short: API
+weight: 90
+# Note: this is a placeholder page. The URL to this page redirects elsewhere.
+---

content/docs/languages/java/generated-code.md

@@ -1,6 +1,7 @@
 ---
 title: Java Generated-code Reference
 short: Generated Code
+weight: 80
 ---
 
 ## Packages

content/docs/languages/kotlin/_index.md

@@ -1,9 +1,10 @@
 ---
 title: Kotlin/JVM
+api_path: javadocs.dev/io.grpc/grpc-kotlin-stub/latest?ext=1
 ---
 
 These language-specific pages are available:
 
 - [Quick start](quickstart)
 - [Basics tutorial](basics)
-- [API reference](https://javadocs.dev/io.grpc/grpc-kotlin-stub/latest)
+- [API reference](api/{{< param api_path >}})

content/docs/languages/kotlin/api.md

@@ -0,0 +1,6 @@
+---
+title: API reference
+short: API
+weight: 90
+# Note: this is a placeholder page. The URL to this page redirects elsewhere.
+---

content/docs/languages/node/_index.md

@@ -6,4 +6,4 @@ These language-specific pages are available:
 
 - [Quick start](quickstart)
 - [Basics tutorial](basics)
-- [API reference](https://grpc.github.io/grpc/node)
+- [API reference](api)

content/docs/languages/node/api.md

@@ -0,0 +1,6 @@
+---
+title: API reference
+short: API
+weight: 90
+# Note: this is a placeholder page. The URL to this page redirects elsewhere.
+---

content/docs/languages/objective-c/_index.md

@@ -1,5 +1,6 @@
 ---
 title: Objective-C
+api_path: grpc/objc
 ---
 
 These language-specific pages are available:
@@ -7,4 +8,4 @@ These language-specific pages are available:
 - [Quick start](quickstart)
 - [Basics tutorial](basics)
 - [OAuth2 tutorial](oauth2)
-- [API reference](https://grpc.github.io/grpc/objc)
+- [API reference](api/{{< param api_path >}})

content/docs/languages/objective-c/api.md

@@ -0,0 +1,6 @@
+---
+title: API reference
+short: API
+weight: 90
+# Note: this is a placeholder page. The URL to this page redirects elsewhere.
+---

content/docs/languages/objective-c/oauth2.md

@@ -1,5 +1,6 @@
 ---
 title: OAuth2
+weight: 60
 ---
 
 This example demonstrates how to use OAuth2 on gRPC to make

content/docs/languages/php/_index.md

@@ -1,9 +1,10 @@
 ---
 title: PHP
+api_path: namespace-Grpc
 ---
 
 These language-specific pages are available:
 
 - [Quick start](quickstart)
 - [Basics tutorial](basics)
-- [API reference](https://grpc.github.io/grpc/php/namespace-Grpc)
+- [API reference](api/{{< param api_path >}})

content/docs/languages/php/api.md

@@ -0,0 +1,6 @@
+---
+title: API reference
+short: API
+weight: 90
+# Note: this is a placeholder page. The URL to this page redirects elsewhere.
+---

content/docs/languages/python/_index.md

@@ -7,4 +7,4 @@ These language-specific pages are available:
 - [Quick start](quickstart)
 - [Basics tutorial](basics)
 - [Generated-code reference](generated-code)
-- [API reference](https://grpc.github.io/grpc/python)
+- [API reference](api)

content/docs/languages/python/api.md

@@ -0,0 +1,6 @@
+---
+title: API reference
+short: API
+weight: 90
+# Note: this is a placeholder page. The URL to this page redirects elsewhere.
+---

content/docs/languages/python/generated-code.md

@@ -1,6 +1,7 @@
 ---
 title: Python Generated-code Reference
 short: Generated Code
+weight: 80
 ---
 
 ## Introduction

content/docs/languages/ruby/_index.md

@@ -1,9 +1,10 @@
 ---
 title: Ruby
+api_path: rubydoc.info/gems/grpc?ext=1
 ---
 
 These language-specific pages are available:
 
 - [Quick start](quickstart)
 - [Basics tutorial](basics)
-- [API reference](https://www.rubydoc.info/gems/grpc)
+- [API reference](api/{{< param api_path >}})

content/docs/languages/ruby/api.md

@@ -0,0 +1,6 @@
+---
+title: API reference
+short: API
+weight: 90
+# Note: this is a placeholder page. The URL to this page redirects elsewhere.
+---

layouts/_default/_markup/render-link.html

@@ -1,4 +1,4 @@
-{{ $isExternal := hasPrefix .Destination "http" -}}
+{{ $isExternal := or (hasPrefix .Destination "http") (findRE "^(|../|/docs/languages/.+?/)api(/.*)?(\\?.*)?$" .Destination) -}}
 <a href="{{ .Destination | safeURL }}"
   {{- with .Title }} title="{{ . }}"{{ end -}}
   {{- if $isExternal }} target="_blank" rel="noopener"{{ end -}}

layouts/index.redirects

@@ -12,8 +12,19 @@
 /docs/reference/:lang/generated-code  /docs/languages/:lang/generated-code
 /docs/tutorials/basic/:lang           /docs/languages/:lang/basics
 
-# These redirect rules are for API reference docs. For a list of
+# API reference docs (prior to 2020/06)
-# source URLs, see the apis.yaml file.
 
 /grpc/*  https://grpc.github.io/grpc/:splat
 /grpc-*  https://grpc.github.io/grpc-:splat
+
+# API reference docs
+
+# API docs hosted on an external site other than grpc.github.io
+/docs/languages/:_/api/* ext=:_  https://:splat
+
+# API hosted on grpc.github.io using path indicated by splat
+/docs/languages/:_/api/grpc/*  https://grpc.github.io/grpc/:splat
+/docs/languages/:_/api/grpc-*  https://grpc.github.io/grpc-:splat
+
+# Base rule: API hosted on grpc.github.io
+/docs/languages/:lang/api/*  https://grpc.github.io/grpc/:lang/:splat 301!

layouts/partials/nav.html

@@ -58,9 +58,20 @@
           <ul class="nav-section-links" x-show="open">
             {{ range $children -}}
               {{ $isActive := eq $here .RelPermalink -}}
+              {{ $isApi :=  findRE "^/docs/languages/.+?/api(/.*)?(\\?.*)?$" .RelPermalink -}}
+              {{ $isExternal := or (hasPrefix .RelPermalink "http") $isApi -}}
+              {{ $href := .RelPermalink -}}
+              {{ if and $isApi .Parent.Params.api_path -}}
+                {{ $href = printf "%s%s" $href .Parent.Params.api_path -}}
+              {{ end -}}
               <li class="nav-section-link{{ if $isActive }} is-active{{ end }}">
-                <a href="{{ .RelPermalink }}">
+                <a href="{{ $href }}"
-                  {{ .Params.short | default .Title }}
+                  {{- if $isExternal }} target="_blank" rel="noopener"{{ end -}}
+                >
+                  {{- .Params.short | default .Title -}}
+                  {{ if $isExternal -}}
+                    <i class="fas fa-external-link-alt"></i>
+                  {{- end -}}
                 </a>
               </li>
             {{ end -}}