From 9c550739eef75a44b750ce43114888d729bcabeb Mon Sep 17 00:00:00 2001 From: Adam Altman Date: Wed, 29 Sep 2021 00:06:39 -0500 Subject: [PATCH] demo: show how to use multiple APIs with different sidebars configurations --- combined/index.md | 15 +++++++++++++++ combined/paper.page.yaml | 12 ++++++++++++ combined/rock.page.yaml | 10 ++++++++++ combined/scissors.page.yaml | 12 ++++++++++++ drilldown/index.md | 33 +++++++++++++++++++++++++++++++++ drilldown/paper.page.yaml | 12 ++++++++++++ drilldown/rock.page.yaml | 10 ++++++++++ drilldown/scissors.page.yaml | 12 ++++++++++++ openapi/paper.page.yaml | 5 ++--- openapi/rock.page.yaml | 13 +++++-------- openapi/scissors.page.yaml | 5 ++--- separated/index.md | 29 +++++++++++++++++++++++++++++ separated/paper.page.yaml | 12 ++++++++++++ separated/rock-quickstart.md | 3 +++ separated/rock.page.yaml | 10 ++++++++++ separated/scissors.page.yaml | 12 ++++++++++++ sidebars.yaml | 35 ++++++++++++++++++++++------------- siteConfig.yaml | 9 +++++++++ 18 files changed, 222 insertions(+), 27 deletions(-) create mode 100644 combined/index.md create mode 100644 combined/paper.page.yaml create mode 100644 combined/rock.page.yaml create mode 100644 combined/scissors.page.yaml create mode 100644 drilldown/index.md create mode 100644 drilldown/paper.page.yaml create mode 100644 drilldown/rock.page.yaml create mode 100644 drilldown/scissors.page.yaml create mode 100644 separated/index.md create mode 100644 separated/paper.page.yaml create mode 100644 separated/rock-quickstart.md create mode 100644 separated/rock.page.yaml create mode 100644 separated/scissors.page.yaml diff --git a/combined/index.md b/combined/index.md new file mode 100644 index 00000000..e4cbd11c --- /dev/null +++ b/combined/index.md @@ -0,0 +1,15 @@ +# Combined sidebars + +This puts multiple APIs into a single visible sidebar. + +```yaml +combined: + - page: combined/index.md + - page: combined/rock.page.yaml + - page: combined/paper.page.yaml + - page: combined/scissors.page.yaml +``` + +:::note Pagination +We've paginated the rock, paper, and scissors APIs differently as well. +::: diff --git a/combined/paper.page.yaml b/combined/paper.page.yaml new file mode 100644 index 00000000..50e3551c --- /dev/null +++ b/combined/paper.page.yaml @@ -0,0 +1,12 @@ +type: reference-docs +definitionId: paper +settings: + pagination: section + generateCodeSamples: + languages: + - lang: curl + - lang: JavaScript + - lang: Node.js + - lang: Python + - lang: C# + - lang: Java diff --git a/combined/rock.page.yaml b/combined/rock.page.yaml new file mode 100644 index 00000000..238acd89 --- /dev/null +++ b/combined/rock.page.yaml @@ -0,0 +1,10 @@ +type: reference-docs +definitionId: rock +settings: + pagination: none + generateCodeSamples: + languages: + - lang: curl + - lang: Go + - lang: PHP + - lang: Ruby diff --git a/combined/scissors.page.yaml b/combined/scissors.page.yaml new file mode 100644 index 00000000..f413d79d --- /dev/null +++ b/combined/scissors.page.yaml @@ -0,0 +1,12 @@ +type: reference-docs +definitionId: scissors +settings: + pagination: item + generateCodeSamples: + languages: + - lang: curl + - lang: JavaScript + - lang: Node.js + - lang: Python + - lang: C# + - lang: Java diff --git a/drilldown/index.md b/drilldown/index.md new file mode 100644 index 00000000..d7680b8c --- /dev/null +++ b/drilldown/index.md @@ -0,0 +1,33 @@ +# Drilldown style of sidebars + +This shows the drilldown style of sidebars. + +Notice that the `/*` is appended to the `rock.page.yaml` and `paper.page.yaml` files to avoid an extra group. +We remove the `/*` from the `scissors.page.yaml` file so you can see the difference. + +```yaml +drilldown-style: + - page: drilldown/index.md + - group: Rock + menuStyle: drilldown + icon: images/rock.png + sublabel: Rock API docs + pages: + - page: openapi/rock.page.yaml/* + - group: Paper + menuStyle: drilldown + icon: images/paper.png + sublabel: Paper API docs + pages: + - page: openapi/paper.page.yaml/* + - group: Scissors + menuStyle: drilldown + icon: images/scissors.png + sublabel: Scissors API docs + pages: + - page: openapi/scissors.page.yaml +``` + +:::note Pagination +We've paginated the rock, paper, and scissors APIs differently as well. +::: diff --git a/drilldown/paper.page.yaml b/drilldown/paper.page.yaml new file mode 100644 index 00000000..50e3551c --- /dev/null +++ b/drilldown/paper.page.yaml @@ -0,0 +1,12 @@ +type: reference-docs +definitionId: paper +settings: + pagination: section + generateCodeSamples: + languages: + - lang: curl + - lang: JavaScript + - lang: Node.js + - lang: Python + - lang: C# + - lang: Java diff --git a/drilldown/rock.page.yaml b/drilldown/rock.page.yaml new file mode 100644 index 00000000..238acd89 --- /dev/null +++ b/drilldown/rock.page.yaml @@ -0,0 +1,10 @@ +type: reference-docs +definitionId: rock +settings: + pagination: none + generateCodeSamples: + languages: + - lang: curl + - lang: Go + - lang: PHP + - lang: Ruby diff --git a/drilldown/scissors.page.yaml b/drilldown/scissors.page.yaml new file mode 100644 index 00000000..f413d79d --- /dev/null +++ b/drilldown/scissors.page.yaml @@ -0,0 +1,12 @@ +type: reference-docs +definitionId: scissors +settings: + pagination: item + generateCodeSamples: + languages: + - lang: curl + - lang: JavaScript + - lang: Node.js + - lang: Python + - lang: C# + - lang: Java diff --git a/openapi/paper.page.yaml b/openapi/paper.page.yaml index 2826bbc7..50e3551c 100644 --- a/openapi/paper.page.yaml +++ b/openapi/paper.page.yaml @@ -1,8 +1,7 @@ -type: redoc +type: reference-docs definitionId: paper -showInfo: true -expand: true settings: + pagination: section generateCodeSamples: languages: - lang: curl diff --git a/openapi/rock.page.yaml b/openapi/rock.page.yaml index 1a3c3eb5..238acd89 100644 --- a/openapi/rock.page.yaml +++ b/openapi/rock.page.yaml @@ -1,13 +1,10 @@ -type: redoc +type: reference-docs definitionId: rock -showInfo: true -expand: true settings: + pagination: none generateCodeSamples: languages: - lang: curl - - lang: JavaScript - - lang: Node.js - - lang: Python - - lang: C# - - lang: Java + - lang: Go + - lang: PHP + - lang: Ruby diff --git a/openapi/scissors.page.yaml b/openapi/scissors.page.yaml index f62b9461..f413d79d 100644 --- a/openapi/scissors.page.yaml +++ b/openapi/scissors.page.yaml @@ -1,8 +1,7 @@ -type: redoc +type: reference-docs definitionId: scissors -showInfo: true -expand: true settings: + pagination: item generateCodeSamples: languages: - lang: curl diff --git a/separated/index.md b/separated/index.md new file mode 100644 index 00000000..61935eef --- /dev/null +++ b/separated/index.md @@ -0,0 +1,29 @@ +# Separate sidebars + +This makes separate sidebars (all within a single `sidebars.yaml` file). + +Notice we use the `/*` to eliminate one grouping level in the scissors and rock APIs. +You will visually see the difference between those and the paper API. + +```yaml +## different sidebars +rock: + - page: separated/rock-quickstart.md + - page: separated/rock.page.yaml/* +paper: + - page: separated/paper.page.yaml +scissors: + - page: separated/scissors.page.yaml/* + +``` + +Use these links to visit those APIs: + +- [Rock](./rock-quickstart.md) +- [Paper](./paper.page.yaml) +- [Scissors](./scissors.page.yaml) + + +:::note Pagination +We've paginated the rock, paper, and scissors APIs differently as well. +::: diff --git a/separated/paper.page.yaml b/separated/paper.page.yaml new file mode 100644 index 00000000..50e3551c --- /dev/null +++ b/separated/paper.page.yaml @@ -0,0 +1,12 @@ +type: reference-docs +definitionId: paper +settings: + pagination: section + generateCodeSamples: + languages: + - lang: curl + - lang: JavaScript + - lang: Node.js + - lang: Python + - lang: C# + - lang: Java diff --git a/separated/rock-quickstart.md b/separated/rock-quickstart.md new file mode 100644 index 00000000..2105e705 --- /dev/null +++ b/separated/rock-quickstart.md @@ -0,0 +1,3 @@ +# Rock Quickstart + +This is a quickstart for the Rock API. diff --git a/separated/rock.page.yaml b/separated/rock.page.yaml new file mode 100644 index 00000000..238acd89 --- /dev/null +++ b/separated/rock.page.yaml @@ -0,0 +1,10 @@ +type: reference-docs +definitionId: rock +settings: + pagination: none + generateCodeSamples: + languages: + - lang: curl + - lang: Go + - lang: PHP + - lang: Ruby diff --git a/separated/scissors.page.yaml b/separated/scissors.page.yaml new file mode 100644 index 00000000..f413d79d --- /dev/null +++ b/separated/scissors.page.yaml @@ -0,0 +1,12 @@ +type: reference-docs +definitionId: scissors +settings: + pagination: item + generateCodeSamples: + languages: + - lang: curl + - lang: JavaScript + - lang: Node.js + - lang: Python + - lang: C# + - lang: Java diff --git a/sidebars.yaml b/sidebars.yaml index a6bd4d13..0dbaebe8 100644 --- a/sidebars.yaml +++ b/sidebars.yaml @@ -71,28 +71,37 @@ alternative: label: Alternative sidebar example ## different sidebars -# rock: -# - page: openapi/rock.page.yaml -# paper: -# - page: openapi/paper.page.yaml -# scissors: -# - page: openapi/scissors.page.yaml/* +rock: + - page: separated/rock-quickstart.md + - page: separated/rock.page.yaml/* +paper: + - page: separated/paper.page.yaml +scissors: + - page: separated/scissors.page.yaml/* -# unified-sidebar: -# - page: openapi/rock.page.yaml -# - page: openapi/paper.page.yaml -# - page: openapi/scissors.page.yaml +combined: + - page: combined/index.md + - page: combined/rock.page.yaml + - page: combined/paper.page.yaml + - page: combined/scissors.page.yaml drilldown-style: + - page: drilldown/index.md - group: Rock menuStyle: drilldown + icon: images/rock.png + sublabel: Rock API docs pages: - - page: openapi/rock.page.yaml/* + - page: drilldown/rock.page.yaml/* - group: Paper menuStyle: drilldown + icon: images/paper.png + sublabel: Paper API docs pages: - - page: openapi/paper.page.yaml/* + - page: drilldown/paper.page.yaml/* - group: Scissors menuStyle: drilldown + icon: images/scissors.png + sublabel: Scissors API docs pages: - - page: openapi/scissors.page.yaml/* + - page: drilldown/scissors.page.yaml diff --git a/siteConfig.yaml b/siteConfig.yaml index afa13300..182e37b1 100644 --- a/siteConfig.yaml +++ b/siteConfig.yaml @@ -34,6 +34,15 @@ nav: - label: Training exercises page: developer-portal/index.md + - label: Drilldown sidebars + page: drilldown/index.md + + - label: Combined sidebars + page: combined/index.md + + - label: Separated sidebars + page: separated/index.md + - label: External docs icon: ./images/redocly-icon-white.png href: https://redoc.ly/docs/developer-portal/introduction/