chore(Documentation): Update documentation to use the ADI Harmonic theme

.github/workflows/build-docs.yml

@@ -41,130 +41,10 @@ jobs:
         uses: actions/[email protected]
         with:
           cache: pip
-          
+
       - name: Install mkdocs
         run: pip install -r Documentation/requirements.txt
 
-      - name: Doxygen (MAX32520)
-        uses: mattnotmitt/[email protected]
-        with:
-          # Path to Doxyfile
-          doxyfile-path: max32520_Doxyfile
-          # Working directory
-          working-directory: Libraries/PeriphDrivers/Documentation
-
-      - name: Doxygen (MAX32570)
-        uses: mattnotmitt/[email protected]
-        with:
-          # Path to Doxyfile
-          doxyfile-path: max32570_Doxyfile
-          # Working directory
-          working-directory: Libraries/PeriphDrivers/Documentation
-
-      - name: Doxygen (MAX32572)
-        uses: mattnotmitt/[email protected]
-        with:
-          # Path to Doxyfile
-          doxyfile-path: max32572_Doxyfile
-          # Working directory
-          working-directory: Libraries/PeriphDrivers/Documentation
-
-      - name: Doxygen (MAX32650)
-        uses: mattnotmitt/[email protected]
-        with:
-          # Path to Doxyfile
-          doxyfile-path: max32650_Doxyfile
-          # Working directory
-          working-directory: Libraries/PeriphDrivers/Documentation
-
-      - name: Doxygen (MAX32655)
-        uses: mattnotmitt/[email protected]
-        with:
-          # Path to Doxyfile
-          doxyfile-path: max32655_Doxyfile
-          # Working directory
-          working-directory: Libraries/PeriphDrivers/Documentation
-
-      - name: Doxygen (MAX32660)
-        uses: mattnotmitt/[email protected]
-        with:
-          # Path to Doxyfile
-          doxyfile-path: max32660_Doxyfile
-          # Working directory
-          working-directory: Libraries/PeriphDrivers/Documentation
-
-      - name: Doxygen (MAX32662)
-        uses: mattnotmitt/[email protected]
-        with:
-          # Path to Doxyfile
-          doxyfile-path: max32662_Doxyfile
-          # Working directory
-          working-directory: Libraries/PeriphDrivers/Documentation
-
-      - name: Doxygen (MAX32665)
-        uses: mattnotmitt/[email protected]
-        with:
-          # Path to Doxyfile
-          doxyfile-path: max32665_Doxyfile
-          # Working directory
-          working-directory: Libraries/PeriphDrivers/Documentation
-
-      - name: Doxygen (MAX32670)
-        uses: mattnotmitt/[email protected]
-        with:
-          # Path to Doxyfile
-          doxyfile-path: max32670_Doxyfile
-          # Working directory
-          working-directory: Libraries/PeriphDrivers/Documentation
-
-      - name: Doxygen (MAX32672)
-        uses: mattnotmitt/[email protected]
-        with:
-          # Path to Doxyfile
-          doxyfile-path: max32672_Doxyfile
-          # Working directory
-          working-directory: Libraries/PeriphDrivers/Documentation
-
-      - name: Doxygen (MAX32675)
-        uses: mattnotmitt/[email protected]
-        with:
-          # Path to Doxyfile
-          doxyfile-path: max32675_Doxyfile
-          # Working directory
-          working-directory: Libraries/PeriphDrivers/Documentation
-
-      - name: Doxygen (MAX32680)
-        uses: mattnotmitt/[email protected]
-        with:
-          # Path to Doxyfile
-          doxyfile-path: max32680_Doxyfile
-          # Working directory
-          working-directory: Libraries/PeriphDrivers/Documentation
-
-      - name: Doxygen (MAX32690)
-        uses: mattnotmitt/[email protected]
-        with:
-          # Path to Doxyfile
-          doxyfile-path: max32690_Doxyfile
-          # Working directory
-          working-directory: Libraries/PeriphDrivers/Documentation
-
-      - name: Doxygen (MAX78000)
-        uses: mattnotmitt/[email protected]
-        with:
-          # Path to Doxyfile
-          doxyfile-path: max78000_Doxyfile
-          # Working directory
-          working-directory: Libraries/PeriphDrivers/Documentation
-
-      - name: Doxygen (MAX78002)
-        uses: mattnotmitt/[email protected]
-        with:
-          # Path to Doxyfile
-          doxyfile-path: max78002_Doxyfile
-          # Working directory
-          working-directory: Libraries/PeriphDrivers/Documentation
-
       - name: Build User Guide
         run: | # Build Documentation Folder and run mkdocs
           python3 Documentation/build.py

.gitignore

@@ -5,8 +5,14 @@ Examples/*/*/*/buildrv
 .vscode/settings.json
 Libraries/PeriphDrivers/Documentation/MAX*
 Libraries/PeriphDrivers/bin
+docs/
 Documentation/Libraries
 Documentation/res
+Documentation/LICENSE.md
+Documentation/README.md
+Documentation/CONTRIBUTING.md
+Documentation/Tools/Bluetooth/README.md
+Documentation/user-guide/examples.md
 Examples/MAX78000/PowerTest
 Examples/MAX32570
 Examples/MAX32572
@@ -21,6 +27,7 @@ Tools/MSYS2
 *.d
 /**/make.log
 /**/.idea/
+/**/.venv/
 /**/venv/
 session.txt.log
 flash.log
@@ -40,4 +47,4 @@ package.json
 mxc_version.h
 mxc_version.mk
 Packetcraft-ADI
-packetcraft-adi
+packetcraft-adi

.markdownlint.yml

@@ -0,0 +1,23 @@
+# start with the default markdownlint configuration
+default: true
+
+# ignore line length limitations
+line-length: false
+
+# prefer # style headings
+heading-style:
+  style: atx
+
+# disable block style checks since they interfere with material admonitions
+code-block-style: false
+
+# default for Python-Markdown is 4 spaces
+ul-indent:
+  indent: 4
+  start_indented: false
+  start_indent: 4
+
+# allow img tags to set specific image sizes
+no-inline-html:
+  allowed_elements:
+    - img

Documentation/CONTRIBUTING.md → CONTRIBUTING.md

@@ -21,41 +21,41 @@ If a direct branch on the mainline MSDK repo is made, the following branch namin
 
 ## PR Title - Subject Responsibilites for Reviewers/Mergers/PR Owners
 
-Format: 
+Format:
 `type(scope)<!>: Subject`
 
 For more information of the format, please review the [pull_request_template.md](https://github.com/analogdevicesinc/msdk/blob/main/Documentation/pull_request_template.md).
 
 These are the rules for the `Subject`.
 
-1.  The first character is capitalized and the subject must not end with any punctuation (!,.?) 
-2.  Use imperative mood in the Subjects - meaning the tone of the Subject should be like giving an order or request.
-    * “Add” instead of “Added” or “Adding”.
-    * “Fix” instead of “Fixed” or “Fixing”.
-    * “Update” instead of “Updated” or “Updating”.
-    * “Delete” instead of “Deleted” or “Deleting”.
-3.  The Subject contents should have useful and concise wording.
-    * No long descriptive subjects - not concise if it gets too descriptive. 
-        * You can be more descriptive in the body or footer of the commit by running:
-        `git commit -m “Title contents” -m “Body contents” -m “Footer contents”` 
-    * No simple titles like “Add small SPI change”
-4.  The Subject should include what parts are affected, if any. Only the parts’ CHIP NAME should be used in the Subject. No die names are allowed.
-    * For the most readability, append the affected parts list at the end of the Subject, so the important, beginning part of the commit message is visible when traversing through the MSDK repo on GitHub.
-    * The list of chip names should be in ascending numerical order in the Subject.
-    * Examples:
+1. The first character is capitalized and the subject must not end with any punctuation (!,.?)
+2. Use imperative mood in the Subjects - meaning the tone of the Subject should be like giving an order or request.
+    - “Add” instead of “Added” or “Adding”.
+    - “Fix” instead of “Fixed” or “Fixing”.
+    - “Update” instead of “Updated” or “Updating”.
+    - “Delete” instead of “Deleted” or “Deleting”.
+3. The Subject contents should have useful and concise wording.
+    - No long descriptive subjects - not concise if it gets too descriptive.
+        - You can be more descriptive in the body or footer of the commit by running:
+        `git commit -m “Title contents” -m “Body contents” -m “Footer contents”`
+    - No simple titles like “Add small SPI change”
+4. The Subject should include what parts are affected, if any. Only the parts’ CHIP NAME should be used in the Subject. No die names are allowed.
+    - For the most readability, append the affected parts list at the end of the Subject, so the important, beginning part of the commit message is visible when traversing through the MSDK repo on GitHub.
+    - The list of chip names should be in ascending numerical order in the Subject.
+    - Examples:
         1. `fix(CMSIS): Rename TRIMSIR registers for MAX32670 and MAX32675`
         2. `fix(Third-Party): Remove USB DMA support for MAX32655, MAX32665, MAX32690, MAX78000, and MAX78002`
         3. `feat(Examples): Add console output in Hello_World READMEs for all parts`
         4. `fix(Examples,PeriphDrivers): Deprecate MXC\_RTC\_GetSecond and MXC\_RTC\_GetSubSecond for all parts except for MAX32520`
-            * Use this type of wording if all but a few parts were affected to shorten the Subject.
-    * **TIP**: The auto-labeler workflow adds part labels to a PR depending on what specific files were updated. Use the list of labels to figure out what parts were affected by the PR's changes.
-5.  If the PR title is related to a Jira ticket or an issue, the Subject should begin with the ticket designation.
-    * Examples:
-        1. `fix(CMSIS): MSDK-123: Add missing I2C Target registers for MAX32670, MAX32672, and MAX32675` 
-        2. `fix(PeriphDrivers): Ticket-321: Fix SPI hanging on 9-bit wide messages for all parts` 
+            - Use this type of wording if all but a few parts were affected to shorten the Subject.
+    - **TIP**: The auto-labeler workflow adds part labels to a PR depending on what specific files were updated. Use the list of labels to figure out what parts were affected by the PR's changes.
+5. If the PR title is related to a Jira ticket or an issue, the Subject should begin with the ticket designation.
+    - Examples:
+        1. `fix(CMSIS): MSDK-123: Add missing I2C Target registers for MAX32670, MAX32672, and MAX32675`
+        2. `fix(PeriphDrivers): Ticket-321: Fix SPI hanging on 9-bit wide messages for all parts`
         3. `fix(Documentation): Issue #123: Revise steps for MSDK installation in the user guides`
-6.  When a merger “Squash and Merges” an approved PR to main, do not delete the PR number that is automatically appended to the title. Ideally, the PR title should be following our rules before approval, so the merger just needs to press the “Squash and Merge” button.
-    * Using previous examples from rule 4, this is what the commit should look like in the main branch:
+6. When a merger “Squash and Merges” an approved PR to main, do not delete the PR number that is automatically appended to the title. Ideally, the PR title should be following our rules before approval, so the merger just needs to press the “Squash and Merge” button.
+    - Using previous examples from rule 4, this is what the commit should look like in the main branch:
         1. `fix(CMSIS): MSDK-123: Add missing I2C Target registers for all parts (#412)`
         2. `fix(PeriphDrivers): Ticket-321: Fix SPI hanging on 9-bit wide messages for all parts (#646)`
         3. `feat(Examples): Add console output in Hello_World READMEs for all parts (#342)`
@@ -64,10 +64,11 @@ These are the rules for the `Subject`.
 Please ensure all actions have passed or successfully completed before merging a PR into `main`. MSDK maintainers have permissions to merge approved PRs even with a failing action.
 
 ## PR Format Rules (Workflow Enforced)
-1.  The type is case-sensitive and must be one of the listed types.
-2.  The scope is case-sensitive and must be one of the listed scopes.
-3.  The first word of the Subject must be capitalized.
-4.  The Subject must not end with any punctuation (periods, commas, exclamation marks).
+
+1. The type is case-sensitive and must be one of the listed types.
+2. The scope is case-sensitive and must be one of the listed scopes.
+3. The first word of the Subject must be capitalized.
+4. The Subject must not end with any punctuation (periods, commas, exclamation marks).
 
 ## Style Guide
 
@@ -115,7 +116,7 @@ clang-format rules are loaded from the **.clang-format** and cpplint rules are l
 #### clang-format
 
 [clang-format](https://www.kernel.org/doc/html/latest/process/clang-format.html) is a code formatter and style checker that enforces a common style for the code-base.
-**The MSDK uses version 14**, which is sometimes not available by default on some Linux distributions.  It can be retrieved from [https://apt.llvm.org/](https://apt.llvm.org/). 
+**The MSDK uses version 14**, which is sometimes not available by default on some Linux distributions.  It can be retrieved from [https://apt.llvm.org/](https://apt.llvm.org/).
 
 1. `cd` into the root directory of the MSDK repo.
 
@@ -256,11 +257,11 @@ DoxyGen is automatically run across the MSDK code as part of the User Guide's bu
 
 ### User Guide
 
-An MSDK User Guide is maintained in the [USERGUIDE.md](USERGUIDE.md) file.  This document contains higher-level usage info for the MSDK.  If a part, IDE, or library is supported by the MSDK then there should be some relevant info in the User Guide covering its setup, configuration, and usage.
+The [MSDK User Guide](Documentation/user-guide/index.md) is maintained in the `Documentation/user-guide` folder.  This document contains higher-level usage info for the MSDK.  If a part, IDE, or library is supported by the MSDK then there should be some relevant info in the User Guide covering its setup, configuration, and usage.
 
 When writing markdown links, relative paths should always be used.  Additionally, links to local files on the user's filesystem **cannot** be used, since the online copy of the docs will throw a 404 on them.  See [Writing Your Docs](https://www.mkdocs.org/user-guide/writing-your-docs/) for more details.
 
-Static resources such as images should be placed in the `res` folder.
+Static resources such as images should be placed in the `user-guide/res` folder.
 
 ### Building the Documentation
 
@@ -276,10 +277,17 @@ To **build** the docs:
 
 1. Install [doxygen](https://www.doxygen.nl/download.html)
 2. Add doxygen's binary diretory to the [Environmental Path](https://learn.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ee537574(v=office.14)) Variable
-3. Install Python 3
-4. `pip install -r Documentation/requirements.txt`
-5. `python Documentation/build.py`
-6. The site will be built in the `docs` folder of the repo.
+3. Install Python 3.10 or greater
+4. Run the following commands
+
+    ```sh
+    python -m venv venv
+    source venv/bin/activate # (MacOS/Linux) or venv\Scripts\activate (Windows)
+    pip install -r Documentation/requirements.txt
+    python Documentation/build.py
+    ```
+
+The site will be built in the `docs` folder of the repo.
 
 To **preview** the generated site: