Refactor FXIOS-11567 [DocC] Updates to CI and Xcode for building docs (#24795)

Author: janbrasna

.github/workflows/firefox-ios-publish-docc.yml

@@ -1,10 +1,12 @@
 name: Deploy Docc
 on:
-  # Runs on pushes where BrowserKit files are modified
+  workflow_dispatch: # Allow manual runs
   push:
-    paths:
+    branches:
+      - main
+    paths: # Only runs on changes to BrowserKit files
       - BrowserKit/Sources/ComponentLibrary/**
-  workflow_dispatch: {} # adding the workflow_dispatch so it can be triggered manually
+      - .github/workflows/firefox-ios-publish-docc.yml
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
@@ -14,7 +16,7 @@ permissions:
 
 # Allow one concurrent deployment
 concurrency:
-  group: "pages"
+  group: github-pages
   cancel-in-progress: true
 
 jobs:
@@ -24,12 +26,15 @@ jobs:
       # Must be set to this for deploying to GitHub Pages
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: macos-13
+    runs-on: macos-15
+    env:
+      XCODE: '16.2'
     steps:
-      - uses: maxim-lobanov/setup-xcode@v1
+      - name: Switch to Xcode ${{env.XCODE}}
+        uses: maxim-lobanov/setup-xcode@v1
         with:
-          xcode-version: '15.0'
-      - name: Checkout 🛎️
+          xcode-version: ${{env.XCODE}}
+      - name: Checkout
         uses: actions/checkout@v4
       - name: Build DocC
         run: |
@@ -42,12 +47,11 @@ jobs:
             --hosting-base-path "firefox-ios" \
             --output-path docs;
           echo "<script>window.location.href += \"/documentation/componentlibrary\"</script>" > docs/index.html;
-          echo "Building DocC step done"
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v1
+        uses: actions/upload-pages-artifact@v3
         with:
           # Upload only docs directory
           path: 'docs'
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v1
+        uses: actions/deploy-pages@v4

.github/workflows/focus-ios-l10n-screenshots.yml

@@ -19,7 +19,7 @@ jobs:
       group2: ${{ steps.my_locales.outputs.group2 }}
       group3: ${{ steps.my_locales.outputs.group3 }}
     steps:
-      - name: Clone firefoxios-l01n repo
+      - name: Clone firefoxios-l10n repo
         uses: actions/checkout@v4
         with:
           repository: mozilla-l10n/firefoxios-l10n
@@ -98,4 +98,4 @@ jobs:
           name: FocusL10nScreenshots
           pattern: Screenshots-*
           delete-merged: true
-          retention-days: 14
+          retention-days: 14

BrowserKit/Sources/ComponentLibrary/Documentation.docc/General Components/ActionFooterView.md

@@ -1,10 +1,10 @@
 # ``ComponentLibrary/ActionFooterView``
 
-A view which is used to contain footer information in form of a title and a link button.
+A view which is used to contain footer information in the form of a title and a link button.
 
 ## Overview
 
-The `ActionFooterView` is a subclass of the `UIView`. You should configure the action footer view content, accessibility identifiers and on tap action through it's view model ``ActionFooterViewModel``. 
+`ActionFooterView` is a subclass of `UIView`. You should configure the action footer view content, accessibility identifiers, and on tap action through its view model ``ActionFooterViewModel``. 
 
 ## Illustration
 

BrowserKit/Sources/ComponentLibrary/Documentation.docc/General Components/BottomSheetViewController.md

@@ -1,10 +1,10 @@
 # ``ComponentLibrary/BottomSheetViewController``
 
-The bottom sheet is a modal view presented from the bottom as a pop over.
+The bottom sheet is a modal view presented from the bottom of the screen as a popover.
 
 ## Overview
 
-The `BottomSheetViewController` is a subclass of the `UIViewController`. The bottom sheet content is another view controller embedded inside this parent view controller. The bottom sheet itself is shown as a popover, meaning it's type of modal. Bottom sheet can be dismissed from the close button, by doing a swipe gesture or by clicking outside the sheet itself. Those properties can be configured with it's view model ``BottomSheetViewModel``.
+`BottomSheetViewController` is a subclass of `UIViewController`. The bottom sheet content is another view controller embedded within this parent view controller. The bottom sheet itself is displayed as a popover, making it a type of modal. It can be dismissed by tapping the close button, performing a swipe gesture, or clicking outside the sheet. These properties can be configured using its view model ``BottomSheetViewModel``.
 
 ## Illustration
 

BrowserKit/Sources/ComponentLibrary/Documentation.docc/General Components/CardView.md

@@ -1,10 +1,10 @@
 # ``ComponentLibrary/CardView``
 
-The card view which is used to contain different type of content.
+The card view which is used to contain different types of content.
 
 ## Overview
 
-The `CardView` is a subclass of the `UIView`. You should configure the card view content, accessibility identifier and background color through it's view model ``CardViewModel``. The rounded corners and padding around the content of the view shouldn't be adjusted and should be used as is. For a card that has shadow, please see ``ShadowCardView``.
+`CardView` is a subclass of `UIView`. You should configure the card view content, accessibility identifier and background color through its view model ``CardViewModel``. The rounded corners and padding around the content of the view shouldn't be adjusted and should be used as is. For a card that has a shadow, please see ``ShadowCardView``.
 
 ## Illustration
 

BrowserKit/Sources/ComponentLibrary/Documentation.docc/General Components/CloseButton.md

@@ -4,7 +4,7 @@ The button which is used for closing a view, such as a bottom sheet, when the us
 
 ## Overview
 
-The `CloseButton` is a subclass of the `UIButton`. This means properties of the `UIButton` are accessible, but for easy convenience it's recommended to configure the button title, font and accessibility identifier through it's view model ``CloseButtonViewModel``. The button size shouldn't be adjusted and should be used as is.
+`CloseButton` is a subclass of `UIButton`. This means that the properties of `UIButton` are accessible, however it's recommended to configure the button title, font, and accessibility identifier through its view model ``CloseButtonViewModel``. The button size shouldn't be adjusted and should be used as is.
 
 ## Illustration
 

BrowserKit/Sources/ComponentLibrary/Documentation.docc/General Components/CollapsibleCardView.md

@@ -1,10 +1,10 @@
 # ``ComponentLibrary/CollapsibleCardView``
 
-The collapsible card view opens to show content with a user press.
+The collapsible card view opens to show content on user press.
 
 ## Overview
 
-The `CollapsibleCardView` is a subclass of the `ShadowCardView`. You should configure the card view content view, accessibility identifier, and state through it's view model ``CollapsibleCardViewModel``. The rounded corners and padding around the content of the view shouldn't be adjusted and should be used as is.
+`CollapsibleCardView` is a subclass of `ShadowCardView`. You should configure the card view content view, accessibility identifier, and state through its view model ``CollapsibleCardViewModel``. The rounded corners and padding around the content of the view shouldn't be adjusted and should be used as is.
 
 ## Illustration
 

BrowserKit/Sources/ComponentLibrary/Documentation.docc/General Components/ContextualHintView.md

@@ -4,7 +4,7 @@ The contextual hint view is a popover to present more context to the user.
 
 ## Overview
 
-The `ContextualHintView` is a subclass of the `UIView`. That view is basically the content that will be enclosed in a popover which includes an arrow. You should configure the contextual hint view arrow direction, title, accessibility identifier, and click actions through it's view model ``ContextualHintViewModel``. The popover size should be set with `preferredContentSize` normally in the `viewDidLayoutSubviews` instance method, as well as setting the `popoverPresentationController` delegate and source view.
+`ContextualHintView` is a subclass of `UIView`. That view is basically the content that will be enclosed in a popover which includes an arrow. You should configure the contextual hint view arrow direction, title, accessibility identifier, and click actions through its view model ``ContextualHintViewModel``. The popover size should be set with `preferredContentSize` normally in the `viewDidLayoutSubviews` instance method, as well as setting the `popoverPresentationController` delegate and source view.
 
 ## Illustration
 

BrowserKit/Sources/ComponentLibrary/Documentation.docc/General Components/HeaderView.md

@@ -4,7 +4,7 @@ The view which is used as a header for sheets, such as a bottom sheet, where som
 
 ## Overview
 
-The `HeaderView` is a subclass of the `UIView`. The view designed to serve as a header in a user interface. It displays a title, subtitle, favicon (icon), a main button and a close button. It also supports accessibility features and customizable theming. It can be used as a header for displaying information about a web page, user profile, or any other context that requires a title, subtitle, and action buttons.
+`HeaderView` is a subclass of `UIView`. The view is designed to serve as a header in a user interface. It displays a title, subtitle, favicon (icon), a main button, and a close button. It also supports accessibility features and customizable theming. It can be used as a header for displaying information about a web page, user profile, or any other context that requires a title, subtitle, and action buttons.
 
 ## Illustration
 

BrowserKit/Sources/ComponentLibrary/Documentation.docc/General Components/LinkButton.md

@@ -1,16 +1,16 @@
 # ``ComponentLibrary/LinkButton``
 
-The button which is used for actions that looks like a webview link.
+The button which is used for actions resembling a webview link.
 
 ## Overview
 
-The `LinkButton` is a subclass of the `UIButton`. This means properties of the `UIButton` are accessible, but for easy convenience it's recommended to configure the button title, font and accessibility identifier through it's' view model ``LinkButtonViewModel``. The colors and spacing of the button although accessible shouldn't be adjusted and should be used as is.
+`LinkButton` is a subclass of `UIButton`. This means properties of `UIButton` are accessible, however it's recommended to configure the button title, font, and accessibility identifier through its view model ``LinkButtonViewModel``. The colors and spacing of the button, although accessible, shouldn't be adjusted and should be used as is.
 
 ## Illustration
 
 > This image is illustrative only. For precise examples of iOS implementation, please run the SampleApplication.
 
-![The LinkButton on iOS]LinkButton
+![The LinkButton on iOS](LinkButton)
 
 ## Topics
 

BrowserKit/Sources/ComponentLibrary/Documentation.docc/General Components/NavigationHeaderView.md

@@ -1,10 +1,10 @@
 # ``ComponentLibrary/NavigationHeaderView``
 
-The view which is used as a header for sheets, such as a bottom sheet, where some details are displayed and offer possibility to navigate between screens.
+The view which is used as a header for sheets, such as a bottom sheet, where some details are displayed, allowing navigation between screens.
 
 ## Overview
 
-The `NavigationHeaderView` is a subclass of the `UIView`. The view is a custom UIView that acts as a navigation header in an interface. It provides a title, a back button, and a close button, making it useful for navigation within menus or modal views. This view is ideal for use in navigation-driven applications where a header is needed to display a title and provide navigation controls for going back or closing a menu.
+`NavigationHeaderView` is a subclass of `UIView`. It's a custom UIView that acts as a navigation header in an interface. It provides a title, a back button, and a close button, making it useful for navigation within menus or modal views. This view is ideal for use in navigation-driven applications where a header is needed to display a title and provide navigation controls for going back or closing a menu.
 
 ## Illustration
 

BrowserKit/Sources/ComponentLibrary/Documentation.docc/General Components/PaddedSwitch.md

@@ -1,10 +1,10 @@
 # ``ComponentLibrary/PaddedSwitch``
 
-The button which is used for toggle actions.
+The control used as an on/off toggle.
 
 ## Overview
 
-The `PaddedSwitch` is a subclass of the `UIView`. It contains a ``ThemedSwitch``, adding some padding for the width of that control. This switch view should be configured through it's view model ``PaddedSwitchViewModel``.
+`PaddedSwitch` is a subclass of `UIView`. It contains a ``ThemedSwitch``, adding some padding for the width of that control. This switch view should be configured through its view model ``PaddedSwitchViewModel``.
 
 ## Illustration
 

BrowserKit/Sources/ComponentLibrary/Documentation.docc/General Components/PrimaryRoundedButton.md

@@ -4,7 +4,7 @@ The button which is used for primary actions.
 
 ## Overview
 
-The `PrimaryRoundedButton` is a subclass of the `UIButton`. This means properties of the `UIButton` are accessible, but for easy convenience it's recommended to configure the button title and accessibility identifier through it's view model ``PrimaryRoundedButtonViewModel``. The colors, rounded corners and spacing of the button although accessible shouldn't be adjusted and should be used as is.
+`PrimaryRoundedButton` is a subclass of `UIButton`. This means that the properties of `UIButton` are accessible, however it's recommended to configure the button title and accessibility identifier through its view model ``PrimaryRoundedButtonViewModel``. The colors, rounded corners, and spacing of the button, although accessible, shouldn't be adjusted and should be used as is.
 
 ## Illustration
 

BrowserKit/Sources/ComponentLibrary/Documentation.docc/General Components/SecondaryRoundedButton.md

@@ -4,7 +4,7 @@ The button which is used for secondary actions.
 
 ## Overview
 
-The `SecondaryRoundedButton` is a subclass of the `UIButton`. This means properties of the `UIButton` are accessible, but for easy convenience it's recommended to configure the button title and accessibility identifier through it's view model ``SecondaryRoundedButtonViewModel``. The colors, rounded corners and spacing of the button although accessible shouldn't be adjusted and should be used as is.
+`SecondaryRoundedButton` is a subclass of `UIButton`. This means that the properties of `UIButton` are accessible, but it's recommended to configure the button title and accessibility identifier through its view model ``SecondaryRoundedButtonViewModel``. The colors, rounded corners, and spacing of the button, although accessible, shouldn't be adjusted and should be used as is.
 
 ## Illustration
 

BrowserKit/Sources/ComponentLibrary/Documentation.docc/General Components/ShadowCardView.md

@@ -1,10 +1,10 @@
 # ``ComponentLibrary/ShadowCardView``
 
-The shadow card view which is used to contain different type of content.
+The shadow card view which is used to contain different types of content.
 
 ## Overview
 
-The `ShadowCardView` is a subclass of the `UIView`. You should configure the shadow card view content and accessibility identifier through it's view model ``ShadowCardViewModel``. The rounded corners, shadow and padding around the content of the view shouldn't be adjusted and should be used as is. For a card without a shadow, please see ``CardView``.
+`ShadowCardView` is a subclass of `UIView`. You should configure the shadow card view content and accessibility identifier through its view model ``ShadowCardViewModel``. The rounded corners, shadow, and padding around the content of the view shouldn't be adjusted and should be used as is. For a card without a shadow see ``CardView``.
 
 ## Illustration
 

BrowserKit/Sources/ComponentLibrary/Documentation.docc/HowToAddNewComponent.md

@@ -25,7 +25,7 @@ You should add the code under the `ComponentLibrary` folder in `BrowserKit`, fol
 1. Ensure your component behaves properly with RTL languages. This means using trailing and leading constraints, and ensure images are flipped where ever needed. See [`imageFlippedForRightToLeftLayoutDirection`](https://developer.apple.com/documentation/uikit/uiimage/1624140-imageflippedforrighttoleftlayout) for more information.
 1. Ensure your component behaves properly with Voice Over. This means we should inject needed identifiers for images to be read out loud to users to have the proper context. As developers, we should ensure the constraints are made properly, so the field highlighted with Voice Over is actually the one being read out loud.
 1. Ensure your component reacts properly to theme manager changes by being `ThemeApplicable`.
-1. Make sure that your component is added to the component library documentation. It needs to be listed in the landing page, as well as having it's own documentation page.
+1. Make sure that your component is added to the component library documentation. It needs to be listed on the landing page, as well as having its own documentation page.
 
 ### Sample application
 > You will need to close the Client application to be able to navigate `BrowserKit` in the Sample application when you open [`Sample app xcodeproj`](https://github.com/mozilla-mobile/firefox-ios/tree/main/SampleComponentLibraryApp)