[#638] Review and improve documentation presentation

Orange-OpenSource · Oct 10, 2023 · 0ee00c1 · 0ee00c1
1 parent 2f296fc
commit 0ee00c1
Show file tree

Hide file tree

Showing 24 changed files with 146 additions and 107 deletions.
diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
@@ -16,7 +16,6 @@ GEM
       http_parser.rb (~> 0)
     eventmachine (1.2.7)
     ffi (1.15.5)
-    ffi (1.15.5-x64-mingw-ucrt)
     ffi (1.15.5-x64-unknown)
     forwardable-extended (2.6.0)
     http_parser.rb (0.8.0)
@@ -83,7 +82,7 @@ GEM
     webrick (1.8.1)
 
 PLATFORMS
-  x64-mingw-ucrt
+  x64-unknown
   x64-unknown
   x86_64-darwin-19
   x86_64-darwin-21

diff --git a/docs/_layouts/main.html b/docs/_layouts/main.html
@@ -17,7 +17,11 @@
         max-height: 100%;
     }
 
-    h4 {
+    h2, h3 {
+        margin-top: 3rem;
+    }
+
+    h4, h5 {
         margin-top: 2rem;
     }
 
@@ -93,8 +97,6 @@
     }
 
 
-
-
     </style>
 
     <title>{{ page.title }}</title>

diff --git a/docs/components/AppBarsBottom.md b/docs/components/AppBarsBottom.md
@@ -4,9 +4,8 @@ title: "App bars: bottom"
 description: A bottom app bar displays navigation and key actions at the bottom of mobile screens.
 ---
 
----
-
-**Page Summary**
+<br>
+**On this page**
 
 * [Specifications references](#specifications-references)
 * [Accessibility](#accessibility)

diff --git a/docs/components/AppBarsTop.md b/docs/components/AppBarsTop.md
@@ -4,9 +4,8 @@ title: "App bars: top"
 description: Top app bars display information and actions relating to the current screen.
 ---
 
----
-
-**Page Summary**
+<br>
+**On this page**
 
 * [Specifications references](#specifications-references)
 * [Accessibility](#accessibility)
@@ -66,8 +65,11 @@ OdsTopAppBar(
 ```
 
 Note: By default, the `OdsTopAppBar` is elevated but you can set `elevated` parameter to `false` if you don't want any shadow below it (for example if you want to display tabs below).
+{:.bd-callout .bd-callout-info}
 
-Parameter | Default value | Description
+##### OdsTopAppBar API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `title: String` | | Title to be displayed in the center of the top app bar
 `modifier: Modifier` | `Modifier` |`Modifier` to be applied to the top app bar
@@ -145,7 +147,9 @@ Scaffold(
 }
 ```
 
-Parameter | Default value | Description
+##### OdsLargeTopAppBar API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `title: String` | | Title displayed in the center of the top app bar
 `modifier: Modifier` | `Modifier` |`Modifier` applied to the top app bar

diff --git a/docs/components/Banners.md b/docs/components/Banners.md
@@ -10,9 +10,8 @@ It requires a user action to be dismissed.
 Banners should be displayed at the top of the screen, below a top app bar. They’re persistent and nonmodal, allowing the user to either ignore them or interact with them at any time.
 Only one banner should be shown at a time
 
----
-
-**Page Summary**
+<br>
+**On this page**
 
 * [Specifications references](#specifications-references)
 * [Accessibility](#accessibility)
@@ -54,7 +53,9 @@ OdsBanner(
 )
 ```
 
-Parameter | Default value | Description
+#### OdsBanner API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `message: String` | | Text displayed into the banner
 `firstButton: OdsBannerButton` | | Principal button displayed in the banner

diff --git a/docs/components/Buttons.md b/docs/components/Buttons.md
@@ -4,9 +4,8 @@ title: Buttons
 description: Buttons allow users to take actions, and make choices, with a single tap.
 ---
 
----
-
-**Page Summary**
+<br>
+**On this page**
 
 * [Specifications references](#specifications-references)
 * [Accessibility](#accessibility)
@@ -78,7 +77,9 @@ OdsButton(
 )
 ```
 
-Parameter | Default value | Description
+##### OdsButton API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `text: String` | | Text displayed into the button
 `onClick: () -> Unit` | | Callback invoked when the button is clicked
@@ -114,7 +115,9 @@ OdsTextButton(
 )
 ```
 
-Parameter | Default value | Description
+##### OdsTextButton API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `text: String` | | Text displayed into the button
 `onClick: () -> Unit` | | Callback invoked on button click
@@ -149,7 +152,9 @@ OdsOutlinedButton(
 )
 ```
 
-Parameter | Default value | Description
+##### OdsOutlinedButton API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `text: String` | | Text displayed into the button
 `onClick: () -> Unit` | | Callback invoked on button click
@@ -188,7 +193,9 @@ OdsTextToggleButtonsRow(
 )
 ```
 
-Parameter | Default value | Description
+##### OdsTextToggleButtonsRow API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `textToggleButtons: List<OdsTextToggleButtonsRowItem>` | | Items displayed into the toggle group
 `selectedIndex: Int` | | `textToggleButtons` list index of the selected button
@@ -223,7 +230,9 @@ OdsIconButton(
 )
 ```
 
-Parameter | Default value | Description
+##### OdsIconButton API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `icon: OdsIconButtonIcon` | | Icon to be drawn into the button
 `onClick: () -> Unit` | | Callback to be invoked when the button is clicked
@@ -259,7 +268,9 @@ OdsIconToggleButton(
 )
 ```
 
-Parameter | Default value | Description
+##### OdsIconToggleButton API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `checked: Boolean` | | Controls the checked state of the button
 `onCheckedChange: (Boolean) -> Unit` | | Callback invoked when the button is checked
@@ -305,7 +316,9 @@ OdsIconToggleButtonsRow(
 )
 ```
 
-Parameter | Default value | Description
+##### OdsIconToggleButtonsRow API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `icons: List<OdsIconToggleButtonsRowIcon>` | | Icons to be displayed into the toggle group
 `selectedIndex: Int` | | `icons` list index of the selected button

diff --git a/docs/components/Cards.md b/docs/components/Cards.md
@@ -4,9 +4,8 @@ title: Cards
 description: Cards contain content and actions about a single subject.
 ---
 
----
-
-**Page Summary**
+<br>
+**On this page**
 
 * [Specifications references](#specifications-references)
 * [Accessibility](#accessibility)
@@ -63,7 +62,9 @@ OdsVerticalImageFirstCard(
 )
 ```
 
-Parameter | Default value | Description
+##### OdsVerticalImageFirstCard API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `title: String` | | Title displayed into the card
 `image: OdsCardImage` | | Image displayed into the card
@@ -111,7 +112,9 @@ OdsVerticalHeaderFirstCard(
 )
 ```
 
-Parameter | Default value | Description
+##### OdsVerticalHeaderFirstCard API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `title: String` | | Title displayed into the card
 `image: OdsCardImage` | | Image displayed into the card
@@ -163,7 +166,9 @@ Row(
 }
 ```
 
-Parameter | Default value | Description
+##### OdsSmallCard API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `title: String` | | Title displayed into the card
 `image: OdsCardImage` | | Image displayed into the card
@@ -206,7 +211,9 @@ OdsHorizontalCard(
 )
 ```
 
-Parameter | Default value | Description
+##### OdsHorizontalCard API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `title: String` | | Title displayed into the card
 `image: OdsCardImage` | | Image displayed into the card

diff --git a/docs/components/Checkboxes.md b/docs/components/Checkboxes.md
@@ -10,9 +10,8 @@ Use checkboxes to:
 * Present a list containing sub-selections
 * Turn an item on or off in a desktop environment
 
----
-
-**Page Summary**
+<br>
+**On this page**
 
 * [Specifications references](#specifications-references)
 * [Accessibility](#accessibility)
@@ -34,11 +33,11 @@ Checkboxes support content labeling for accessibility and are readable by most s
 as TalkBack. Text rendered in check boxes is automatically provided to accessibility services.
 Additional content labels are usually unnecessary.
 
-### Implementation
+## Implementation
 
 ![Checkbox](images/checkbox_light.png) ![Checkbox dark](images/checkbox_dark.png)
 
-#### Jetpack Compose
+### Jetpack Compose
 
 In your composable screen you can use:
 
@@ -51,7 +50,9 @@ OdsCheckbox(
 )
 ```
 
-Parameter | Default value | Description
+#### OdsCheckbox API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `checked: Boolean` | | Controls checked state of the checkbox
 `onCheckedChange: ((Boolean) -> Unit)?` | | Callback invoked on checkbox click. If `null`, then this is passive and relies entirely on a higher-level component to control the checked state.

diff --git a/docs/components/Chips.md b/docs/components/Chips.md
@@ -4,9 +4,8 @@ title: Chips
 description: Chips are compact elements that represent an input, attribute, or action.
 ---
 
----
-
-**Page summary**
+<br>
+**On this page**
 
 * [Specifications references](#specifications-references)
 * [Accessibility](#accessibility)
@@ -71,7 +70,9 @@ OdsChip(
 )
 ```
 
-Parameter | Default value | Description
+##### OdsChip API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `text: String` | | Text to be displayed into the chip
 `onClick: () -> Unit` | | Callback called on chip click
@@ -113,7 +114,7 @@ OdsChip(
 )
 ```
 
-Use the same API as the [Input chip](#input-chip).
+Use the [OdsChip API](#odschip-api).
 
 ### Filter chip
 
@@ -147,7 +148,9 @@ OdsFilterChip(
 )
 ```
 
-Parameter | Default value | Description
+##### OdsFilterChip API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `text: String` | | Text to be displayed into the chip
 `onClick: () -> Unit` | | Callback called on chip click
@@ -188,7 +191,7 @@ OdsChip(
 )
 ```
 
-Use the same API as the [Input chip](#input-chip).
+Use the [OdsChip API](#odschip-api).
 
 ## Related components
 
@@ -218,7 +221,9 @@ OdsChoiceChipsFlowRow(
 )
 ```
 
-Parameter | Default value | Description
+#### OdsChoiceChipsFlowRow API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `value: String` | | Initial value of the choice chips flow row
 `onValueChange: (value: T) -> Unit` | | Callback invoked when the value changes. The new value is provided as parameter.

diff --git a/docs/components/Dialogs.md b/docs/components/Dialogs.md
@@ -11,9 +11,8 @@ or a required action has been taken.
 
 Dialogs are purposefully interruptive, so they should be used sparingly.
 
----
-
-**Page Summary**
+<br>
+**On this page**
 
 * [Specifications references](#specifications-references)
 * [Accessibility](#accessibility)
@@ -55,7 +54,9 @@ OdsAlertDialog(
 )
 ```
 
-Parameter | Default value | Description
+##### OdsAlertDialog API
+
+Parameter | Default&nbsp;value | Description
 -- | -- | --
 `text: String` | | Text displayed into the dialog which presents the details regarding the Dialog's purpose
 `confirmButton: OdsAlertDialogButton` | | Button displayed into the dialog which is meant to confirm a proposed action, thus resolving what triggered the dialog