From af412d33362faa7321bdb118ac499e2ddd4c2f9a Mon Sep 17 00:00:00 2001 From: Adam Dunn Date: Wed, 12 Jun 2024 13:23:36 -0600 Subject: [PATCH 01/21] sandbox env --- .github/workflows/public-site-test.yml | 207 ++++++++++++++++++ .../index.md | 1 + 2 files changed, 208 insertions(+) create mode 100644 .github/workflows/public-site-test.yml diff --git a/.github/workflows/public-site-test.yml b/.github/workflows/public-site-test.yml new file mode 100644 index 000000000..2fdb2270d --- /dev/null +++ b/.github/workflows/public-site-test.yml @@ -0,0 +1,207 @@ +name: "Test Site" + +on: + workflow_dispatch: + pull_request: + branches: [ "develop" ] + +permissions: + id-token: write + contents: read + +jobs: + build: + runs-on: ubuntu-latest + environment: sandbox + steps: + # Clone current repo + - name: Checkout + uses: actions/checkout@v3 + with: + path: src + # ref: develop # <-- required to deploy beta docs + + # npm install + - name: npm install + working-directory: ./src + run: | + npm install + + # compress the images + - name: Compress Images + working-directory: ./src + run: | + node ./scripts/compress.js ./ + + # Clone all the Meadow dependencies adjacent for DocFX build use. + - name: Checkout Meadow.Units side-by-side + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Units + path: Meadow.Units + ref: main + - name: Checkout Meadow.Logging side-by-side + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Logging + path: Meadow.Logging + ref: main + - name: Checkout Meadow.Contracts side-by-side + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Contracts + path: Meadow.Contracts + ref: main + - name: Checkout Meadow.Modbus side-by-side + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Modbus + path: Meadow.Modbus + ref: main + - name: Checkout Meadow.Foundation side-by-side + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Foundation + path: Meadow.Foundation + ref: main + - name: Checkout Meadow.Core side-by-side + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Core + path: Meadow.Core + ref: main + - name: Checkout MQTTnet side-by-side + uses: actions/checkout@v3 + with: + repository: WildernessLabs/MQTTnet + path: MQTTnet + ref: master + - name: Checkout Meadow side-by-side + uses: actions/checkout@v3 + with: + # Private repo requires token access; rest are public repos. + token: ${{ secrets.CI_ACCESS_TOKEN }} + repository: WildernessLabs/Meadow + path: Meadow + ref: main + # Clone more Meadow-related repos for API docs generation (via DocFX). + - name: Checkout Meadow.Foundation.Grove into DocFX-expected Source location + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Foundation.Grove + path: Meadow.Foundation.Grove + ref: main + - name: Checkout Meadow.Foundation.FeatherWings into DocFX-expected Source location + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Foundation.FeatherWings + path: Meadow.Foundation.FeatherWings + ref: main + - name: Checkout Meadow.Foundation.mikroBUS into DocFX-expected Source location + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Foundation.mikroBUS + path: Meadow.Foundation.mikroBUS + ref: main + + # # Set up for DocFX + - name: Setup .NET Core SDK 7.0.x + uses: actions/setup-dotnet@v3 + with: + dotnet-version: | + 7.0.x + - name: Setup NuGet + uses: Nuget/setup-nuget@v1.2.0 + - name: Install DocFX globally + run: | + dotnet tool install --global docfx + - name: Install DocFxMarkdownGen + run: | + dotnet tool install --global DocFxMarkdownGen + - name: Run DocFX + working-directory: ./src/docfx + run: | + docfx docfx.json + - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow + # dfmg uses config.yaml for input/output paths + # Currently config has to be limited to `docfx/api/Meadow`, which means we need to figure out a way to run it for all the other /api directories. + # We might be able to set `env:DFMG_YAML_PATH` and `env:DFMG_OUTPUT_PATH` to the correct values for each repo, to generate them all before merging them together. + # One option is setting `env: {whatever}` via Actions syntax (https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_iddefaultsrun). + working-directory: ./src/docfx/dfmg/Meadow + run: | + dfmg + - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow.Foundation + working-directory: ./src/docfx/dfmg/Meadow.Foundation + run: | + dfmg + - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow.Foundation.CompositeDevices + working-directory: ./src/docfx/dfmg/Meadow.Foundation.CompositeDevices + run: | + dfmg + - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow.Foundation.FeatherWings + working-directory: ./src/docfx/dfmg/Meadow.Foundation.FeatherWings + run: | + dfmg + - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow.Foundation.Grove + working-directory: ./src/docfx/dfmg/Meadow.Foundation.Grove + run: | + dfmg + - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow.Foundation.mikroBUS + working-directory: ./src/docfx/dfmg/Meadow.Foundation.mikroBUS + run: | + dfmg + + # let's add correct slugs. They are important, because things won't build if they dont have "slug: /docs/api/..." + - name: Update slugs in frontmatter. + working-directory: ./src + run: | + node ./scripts/update-frontmatter.js + + # Now we need to take all of the generated class/api reference documentation, and merge + # it into the api-overrides content + - name: Merge api docs together + working-directory: ./src + run: | + node ./scripts/merge-api-overrides.js Meadow.Foundation && + node ./scripts/merge-api-overrides.js Meadow.Foundation.FeatherWings && + node ./scripts/merge-api-overrides.js Meadow.Foundation.Grove && + node ./scripts/merge-api-overrides.js Meadow.Foundation.mikroBUS + + # Let's put the api files where they belong + - name: Copy api files to content locations + working-directory: ./src + run: | + node ./scripts/update-frontmatter.js && + node ./scripts/copy-api.js + + # Fun. Docusaurus isn't resolving the links correctly from many + # of the files output from dfmg. This script should help with that. + - name: Fix api broken links + working-directory: ./src + run: | + node ./scripts/api-broken-link-fixer.js ./docs/api/ + + # - name: Fix Meadow.Foundation periphs broken links + # working-directory: ./src + # run: | + # node ./scripts/meadow-foundation-broken-link-fixer.js + + #docusaurus build + - name: Use Node.js + uses: actions/setup-node@v3 + with: + node-version: 18 + cache: 'npm' + # Tell Node.js to look for the package-lock.json file in the cloned repo location rather than root. + cache-dependency-path: src/package-lock.json + - name: Docusaurus Build and Deploy + working-directory: ./src + run: | + npm run build + - uses: bacongobbler/azure-blob-storage-upload@main + with: + source_dir: './src/build' + container_name: '$web' + connection_string: ${{ secrets.BLOB_CONNECTIONSTRING }} + overwrite: 'true' + #sync: 'true' diff --git a/docfx/api/Meadow.Foundation.CompositeDevices/index.md b/docfx/api/Meadow.Foundation.CompositeDevices/index.md index 7aba47520..8fb0f4421 100644 --- a/docfx/api/Meadow.Foundation.CompositeDevices/index.md +++ b/docfx/api/Meadow.Foundation.CompositeDevices/index.md @@ -1 +1,2 @@ ## Meadow.Foundation.CompositeDevices API Reference Documentation +hi \ No newline at end of file From fc2ba35e6656032df6cd3bbfcc3cd235a17e3dc4 Mon Sep 17 00:00:00 2001 From: Adam Dunn Date: Wed, 12 Jun 2024 14:16:38 -0600 Subject: [PATCH 02/21] composite devices repo added --- .github/workflows/public-site-test.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/public-site-test.yml b/.github/workflows/public-site-test.yml index 2fdb2270d..25371eb37 100644 --- a/.github/workflows/public-site-test.yml +++ b/.github/workflows/public-site-test.yml @@ -85,6 +85,12 @@ jobs: path: Meadow ref: main # Clone more Meadow-related repos for API docs generation (via DocFX). + - name: Checkout Meadow.Foundation.CompositeDevices into DocFX-expected Source location + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Foundation.CompositeDevices + path: Meadow.Foundation.CompositeDevices + ref: main - name: Checkout Meadow.Foundation.Grove into DocFX-expected Source location uses: actions/checkout@v3 with: From ea1413d31131d38dca303857db3e0893bb97f211 Mon Sep 17 00:00:00 2001 From: Adam Dunn Date: Wed, 12 Jun 2024 14:25:53 -0600 Subject: [PATCH 03/21] comment on test site creation --- .github/workflows/public-site-test.yml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/.github/workflows/public-site-test.yml b/.github/workflows/public-site-test.yml index 25371eb37..153d7bc69 100644 --- a/.github/workflows/public-site-test.yml +++ b/.github/workflows/public-site-test.yml @@ -211,3 +211,17 @@ jobs: connection_string: ${{ secrets.BLOB_CONNECTIONSTRING }} overwrite: 'true' #sync: 'true' + + # Post a comment on the pull request + - name: Post comment on pull request + if: github.event_name == 'pull_request' + uses: actions/github-script@v6 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + script: | + github.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: 'Thank you for having the patience of Asclepius. Your test site, "https://developer-docusaurus-a8fqgrg9ecg3cxer.z03.azurefd.net/" is ready to view.' + }) \ No newline at end of file From 94457d5d7725c98e58de36f92b417643bde1955a Mon Sep 17 00:00:00 2001 From: Adam Dunn Date: Wed, 12 Jun 2024 16:25:16 -0600 Subject: [PATCH 04/21] comment test --- .github/workflows/public-site-test.yml | 28 ++++++++++++++------------ 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/.github/workflows/public-site-test.yml b/.github/workflows/public-site-test.yml index 153d7bc69..c5bb5bcd1 100644 --- a/.github/workflows/public-site-test.yml +++ b/.github/workflows/public-site-test.yml @@ -14,6 +14,20 @@ jobs: runs-on: ubuntu-latest environment: sandbox steps: + # Post a comment on the pull request + - name: Post comment on pull request + if: github.event_name == 'pull_request' + uses: actions/github-script@v6 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + script: | + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: 'Thank you for having the patience of Asclepius. Your test site, https://developer-docusaurus-a8fqgrg9ecg3cxer.z03.azurefd.net/ is ready to view.' + }) + # Clone current repo - name: Checkout uses: actions/checkout@v3 @@ -212,16 +226,4 @@ jobs: overwrite: 'true' #sync: 'true' - # Post a comment on the pull request - - name: Post comment on pull request - if: github.event_name == 'pull_request' - uses: actions/github-script@v6 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - script: | - github.issues.createComment({ - issue_number: context.issue.number, - owner: context.repo.owner, - repo: context.repo.repo, - body: 'Thank you for having the patience of Asclepius. Your test site, "https://developer-docusaurus-a8fqgrg9ecg3cxer.z03.azurefd.net/" is ready to view.' - }) \ No newline at end of file + \ No newline at end of file From c2d43b47b0ddd2d7f91015dafbaa0b891bf76067 Mon Sep 17 00:00:00 2001 From: Adam Dunn Date: Wed, 12 Jun 2024 16:29:14 -0600 Subject: [PATCH 05/21] comment test --- .github/workflows/public-site-test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/public-site-test.yml b/.github/workflows/public-site-test.yml index c5bb5bcd1..0aee0a070 100644 --- a/.github/workflows/public-site-test.yml +++ b/.github/workflows/public-site-test.yml @@ -19,7 +19,7 @@ jobs: if: github.event_name == 'pull_request' uses: actions/github-script@v6 with: - github-token: ${{ secrets.GITHUB_TOKEN }} + github-token: ${{ secrets.CI_ACCESS_TOKEN }} script: | github.rest.issues.createComment({ issue_number: context.issue.number, From f78770db49830967b80716901ae4d7246ad1a985 Mon Sep 17 00:00:00 2001 From: Adam Dunn Date: Wed, 12 Jun 2024 16:35:49 -0600 Subject: [PATCH 06/21] moved the comment to the end --- .github/workflows/public-site-test.yml | 29 +++++++++++++------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/.github/workflows/public-site-test.yml b/.github/workflows/public-site-test.yml index 0aee0a070..fdc9bcd2f 100644 --- a/.github/workflows/public-site-test.yml +++ b/.github/workflows/public-site-test.yml @@ -14,20 +14,7 @@ jobs: runs-on: ubuntu-latest environment: sandbox steps: - # Post a comment on the pull request - - name: Post comment on pull request - if: github.event_name == 'pull_request' - uses: actions/github-script@v6 - with: - github-token: ${{ secrets.CI_ACCESS_TOKEN }} - script: | - github.rest.issues.createComment({ - issue_number: context.issue.number, - owner: context.repo.owner, - repo: context.repo.repo, - body: 'Thank you for having the patience of Asclepius. Your test site, https://developer-docusaurus-a8fqgrg9ecg3cxer.z03.azurefd.net/ is ready to view.' - }) - + # Clone current repo - name: Checkout uses: actions/checkout@v3 @@ -226,4 +213,16 @@ jobs: overwrite: 'true' #sync: 'true' - \ No newline at end of file + # Post a comment on the pull request + - name: Post comment on pull request + if: github.event_name == 'pull_request' + uses: actions/github-script@v6 + with: + github-token: ${{ secrets.CI_ACCESS_TOKEN }} + script: | + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: 'Thank you for having the patience of Asclepius. Your test site, https://developer-docusaurus-a8fqgrg9ecg3cxer.z03.azurefd.net/ is ready to view.' + }) \ No newline at end of file From fe7b159616a457cd890f2c0c3bcc6a9164b3e652 Mon Sep 17 00:00:00 2001 From: Adam Dunn Date: Wed, 12 Jun 2024 17:02:30 -0600 Subject: [PATCH 07/21] comment test --- .github/workflows/public-site-test.yml | 34 ++++++++++++-------------- 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/.github/workflows/public-site-test.yml b/.github/workflows/public-site-test.yml index fdc9bcd2f..0b5764b48 100644 --- a/.github/workflows/public-site-test.yml +++ b/.github/workflows/public-site-test.yml @@ -5,16 +5,26 @@ on: pull_request: branches: [ "develop" ] -permissions: - id-token: write - contents: read - jobs: build: runs-on: ubuntu-latest environment: sandbox steps: - + # Post a comment on the pull request + - name: Post comment on pull request + if: github.event_name == 'pull_request' + uses: actions/github-script@v6 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + + script: | + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: 'Thank you for having the patience of Asclepius. Your test site, https://developer-docusaurus-a8fqgrg9ecg3cxer.z03.azurefd.net/ is ready to view.' + }) + # Clone current repo - name: Checkout uses: actions/checkout@v3 @@ -213,16 +223,4 @@ jobs: overwrite: 'true' #sync: 'true' - # Post a comment on the pull request - - name: Post comment on pull request - if: github.event_name == 'pull_request' - uses: actions/github-script@v6 - with: - github-token: ${{ secrets.CI_ACCESS_TOKEN }} - script: | - github.rest.issues.createComment({ - issue_number: context.issue.number, - owner: context.repo.owner, - repo: context.repo.repo, - body: 'Thank you for having the patience of Asclepius. Your test site, https://developer-docusaurus-a8fqgrg9ecg3cxer.z03.azurefd.net/ is ready to view.' - }) \ No newline at end of file + \ No newline at end of file From 37b06b83a49296104b3ad1fe89a9b279c286571a Mon Sep 17 00:00:00 2001 From: Adam Dunn Date: Wed, 12 Jun 2024 17:25:12 -0600 Subject: [PATCH 08/21] moved the comment to the bottom --- .github/workflows/public-site-test.yml | 31 +++++++++++++------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/.github/workflows/public-site-test.yml b/.github/workflows/public-site-test.yml index 0b5764b48..0aa9ed0c5 100644 --- a/.github/workflows/public-site-test.yml +++ b/.github/workflows/public-site-test.yml @@ -10,21 +10,7 @@ jobs: runs-on: ubuntu-latest environment: sandbox steps: - # Post a comment on the pull request - - name: Post comment on pull request - if: github.event_name == 'pull_request' - uses: actions/github-script@v6 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - - script: | - github.rest.issues.createComment({ - issue_number: context.issue.number, - owner: context.repo.owner, - repo: context.repo.repo, - body: 'Thank you for having the patience of Asclepius. Your test site, https://developer-docusaurus-a8fqgrg9ecg3cxer.z03.azurefd.net/ is ready to view.' - }) - + # Clone current repo - name: Checkout uses: actions/checkout@v3 @@ -223,4 +209,17 @@ jobs: overwrite: 'true' #sync: 'true' - \ No newline at end of file + # Post a comment on the pull request + - name: Post comment on pull request + if: github.event_name == 'pull_request' + uses: actions/github-script@v6 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + + script: | + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: 'Thank you for having the patience of Asclepius. Your test site, https://developer-docusaurus-a8fqgrg9ecg3cxer.z03.azurefd.net/ is ready to view.' + }) \ No newline at end of file From 691725fd79f25f6c30c54b6d42852de2cc28b9aa Mon Sep 17 00:00:00 2001 From: Adam Dunn Date: Fri, 14 Jun 2024 08:34:40 -0600 Subject: [PATCH 09/21] added conditional api building check --- .github/workflows/public-site-test.yml | 25 +++++++++++++++++++++++++ .github/workflows/publish-site-beta.yml | 7 +++++++ .github/workflows/publish-site-prod.yml | 6 ++++++ 3 files changed, 38 insertions(+) diff --git a/.github/workflows/public-site-test.yml b/.github/workflows/public-site-test.yml index 0aa9ed0c5..e690dd27e 100644 --- a/.github/workflows/public-site-test.yml +++ b/.github/workflows/public-site-test.yml @@ -32,48 +32,56 @@ jobs: # Clone all the Meadow dependencies adjacent for DocFX build use. - name: Checkout Meadow.Units side-by-side + if: contains(github.event.pull_request.title, '[build-api]') uses: actions/checkout@v3 with: repository: WildernessLabs/Meadow.Units path: Meadow.Units ref: main - name: Checkout Meadow.Logging side-by-side + if: contains(github.event.pull_request.title, '[build-api]') uses: actions/checkout@v3 with: repository: WildernessLabs/Meadow.Logging path: Meadow.Logging ref: main - name: Checkout Meadow.Contracts side-by-side + if: contains(github.event.pull_request.title, '[build-api]') uses: actions/checkout@v3 with: repository: WildernessLabs/Meadow.Contracts path: Meadow.Contracts ref: main - name: Checkout Meadow.Modbus side-by-side + if: contains(github.event.pull_request.title, '[build-api]') uses: actions/checkout@v3 with: repository: WildernessLabs/Meadow.Modbus path: Meadow.Modbus ref: main - name: Checkout Meadow.Foundation side-by-side + if: contains(github.event.pull_request.title, '[build-api]') uses: actions/checkout@v3 with: repository: WildernessLabs/Meadow.Foundation path: Meadow.Foundation ref: main - name: Checkout Meadow.Core side-by-side + if: contains(github.event.pull_request.title, '[build-api]') uses: actions/checkout@v3 with: repository: WildernessLabs/Meadow.Core path: Meadow.Core ref: main - name: Checkout MQTTnet side-by-side + if: contains(github.event.pull_request.title, '[build-api]') uses: actions/checkout@v3 with: repository: WildernessLabs/MQTTnet path: MQTTnet ref: master - name: Checkout Meadow side-by-side + if: contains(github.event.pull_request.title, '[build-api]') uses: actions/checkout@v3 with: # Private repo requires token access; rest are public repos. @@ -83,12 +91,14 @@ jobs: ref: main # Clone more Meadow-related repos for API docs generation (via DocFX). - name: Checkout Meadow.Foundation.CompositeDevices into DocFX-expected Source location + if: contains(github.event.pull_request.title, '[build-api]') uses: actions/checkout@v3 with: repository: WildernessLabs/Meadow.Foundation.CompositeDevices path: Meadow.Foundation.CompositeDevices ref: main - name: Checkout Meadow.Foundation.Grove into DocFX-expected Source location + if: contains(github.event.pull_request.title, '[build-api]') uses: actions/checkout@v3 with: repository: WildernessLabs/Meadow.Foundation.Grove @@ -101,6 +111,7 @@ jobs: path: Meadow.Foundation.FeatherWings ref: main - name: Checkout Meadow.Foundation.mikroBUS into DocFX-expected Source location + if: contains(github.event.pull_request.title, '[build-api]') uses: actions/checkout@v3 with: repository: WildernessLabs/Meadow.Foundation.mikroBUS @@ -109,23 +120,29 @@ jobs: # # Set up for DocFX - name: Setup .NET Core SDK 7.0.x + if: contains(github.event.pull_request.title, '[build-api]') uses: actions/setup-dotnet@v3 with: dotnet-version: | 7.0.x - name: Setup NuGet + if: contains(github.event.pull_request.title, '[build-api]') uses: Nuget/setup-nuget@v1.2.0 - name: Install DocFX globally + if: contains(github.event.pull_request.title, '[build-api]') run: | dotnet tool install --global docfx - name: Install DocFxMarkdownGen + if: contains(github.event.pull_request.title, '[build-api]') run: | dotnet tool install --global DocFxMarkdownGen - name: Run DocFX + if: contains(github.event.pull_request.title, '[build-api]') working-directory: ./src/docfx run: | docfx docfx.json - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow + if: contains(github.event.pull_request.title, '[build-api]') # dfmg uses config.yaml for input/output paths # Currently config has to be limited to `docfx/api/Meadow`, which means we need to figure out a way to run it for all the other /api directories. # We might be able to set `env:DFMG_YAML_PATH` and `env:DFMG_OUTPUT_PATH` to the correct values for each repo, to generate them all before merging them together. @@ -134,28 +151,34 @@ jobs: run: | dfmg - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow.Foundation + if: contains(github.event.pull_request.title, '[build-api]') working-directory: ./src/docfx/dfmg/Meadow.Foundation run: | dfmg - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow.Foundation.CompositeDevices + if: contains(github.event.pull_request.title, '[build-api]') working-directory: ./src/docfx/dfmg/Meadow.Foundation.CompositeDevices run: | dfmg - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow.Foundation.FeatherWings + if: contains(github.event.pull_request.title, '[build-api]') working-directory: ./src/docfx/dfmg/Meadow.Foundation.FeatherWings run: | dfmg - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow.Foundation.Grove + if: contains(github.event.pull_request.title, '[build-api]') working-directory: ./src/docfx/dfmg/Meadow.Foundation.Grove run: | dfmg - name: Run DocFxMarkdownGen (dfmg) to generate API .md files for Meadow.Foundation.mikroBUS + if: contains(github.event.pull_request.title, '[build-api]') working-directory: ./src/docfx/dfmg/Meadow.Foundation.mikroBUS run: | dfmg # let's add correct slugs. They are important, because things won't build if they dont have "slug: /docs/api/..." - name: Update slugs in frontmatter. + if: contains(github.event.pull_request.title, '[build-api]') working-directory: ./src run: | node ./scripts/update-frontmatter.js @@ -163,6 +186,7 @@ jobs: # Now we need to take all of the generated class/api reference documentation, and merge # it into the api-overrides content - name: Merge api docs together + if: contains(github.event.pull_request.title, '[build-api]') working-directory: ./src run: | node ./scripts/merge-api-overrides.js Meadow.Foundation && @@ -172,6 +196,7 @@ jobs: # Let's put the api files where they belong - name: Copy api files to content locations + if: contains(github.event.pull_request.title, '[build-api]') working-directory: ./src run: | node ./scripts/update-frontmatter.js && diff --git a/.github/workflows/publish-site-beta.yml b/.github/workflows/publish-site-beta.yml index 0a13bbf26..d97918422 100644 --- a/.github/workflows/publish-site-beta.yml +++ b/.github/workflows/publish-site-beta.yml @@ -93,6 +93,13 @@ jobs: path: Meadow ref: main # Clone more Meadow-related repos for API docs generation (via DocFX). + - name: Checkout Meadow.Foundation.CompositeDevices into DocFX-expected Source location + if: contains(github.event.pull_request.title, '[build-api]') + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Foundation.CompositeDevices + path: Meadow.Foundation.CompositeDevices + ref: main - name: Checkout Meadow.Foundation.Grove into DocFX-expected Source location if: contains(github.event.pull_request.title, '[build-api]') uses: actions/checkout@v3 diff --git a/.github/workflows/publish-site-prod.yml b/.github/workflows/publish-site-prod.yml index 6d2371968..364da076c 100644 --- a/.github/workflows/publish-site-prod.yml +++ b/.github/workflows/publish-site-prod.yml @@ -85,6 +85,12 @@ jobs: path: Meadow ref: main # Clone more Meadow-related repos for API docs generation (via DocFX). + - name: Checkout Meadow.Foundation.CompositeDevices into DocFX-expected Source location + uses: actions/checkout@v3 + with: + repository: WildernessLabs/Meadow.Foundation.CompositeDevices + path: Meadow.Foundation.CompositeDevices + ref: main - name: Checkout Meadow.Foundation.Grove into DocFX-expected Source location uses: actions/checkout@v3 with: From 6729e559e4fce4b0e59e4fc8b51b43c441dfb672 Mon Sep 17 00:00:00 2001 From: Adam Dunn Date: Fri, 14 Jun 2024 09:07:17 -0600 Subject: [PATCH 10/21] featherwings --- .github/workflows/public-site-test.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/public-site-test.yml b/.github/workflows/public-site-test.yml index e690dd27e..640cf614d 100644 --- a/.github/workflows/public-site-test.yml +++ b/.github/workflows/public-site-test.yml @@ -105,6 +105,7 @@ jobs: path: Meadow.Foundation.Grove ref: main - name: Checkout Meadow.Foundation.FeatherWings into DocFX-expected Source location + if: contains(github.event.pull_request.title, '[build-api]') uses: actions/checkout@v3 with: repository: WildernessLabs/Meadow.Foundation.FeatherWings From c0a57e1114a2adc33f2e532019cdc8d91c5e45d6 Mon Sep 17 00:00:00 2001 From: Adam Patridge Date: Sun, 16 Jun 2024 14:22:25 -0600 Subject: [PATCH 11/21] Add Meadow.Cloud logging NuGet dependency --- docs/Meadow/Meadow.Cloud/Logs_Events/index.md | 32 ++++++++++--------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/docs/Meadow/Meadow.Cloud/Logs_Events/index.md b/docs/Meadow/Meadow.Cloud/Logs_Events/index.md index f1dcefe93..71d38b298 100644 --- a/docs/Meadow/Meadow.Cloud/Logs_Events/index.md +++ b/docs/Meadow/Meadow.Cloud/Logs_Events/index.md @@ -6,25 +6,27 @@ subtitle: Getting started with logs and events ## Enabling CloudLogger -Today, logging output through `Resolver.Log.Info("foo bar");` writes to the console. This is great if you are working locally, connected to the device, but not so much when the device is deployed out in the field. Fortunately, getting the same logs in Meadow.Cloud is really simple. +Today, logging output through `Resolver.Log.Info("foo bar")` writes to the console. This is great if you are working locally, connected to the device, but not so much when the device is deployed out in the field. Fortunately, you can also send the same logs to Meadow.Cloud with a few extra steps. -Setting up logs and events requires the following update in `app.config.yaml`: +1. Install the [**Meadow.Logging.LogProviders** NuGet package](https://www.nuget.org/packages/Meadow.Logging.LogProviders) into your project for access to the `CloudLogger` class. -```yaml -MeadowCloud: - Enabled: true -``` +1. Enable Meadow.Cloud logging in your project's `app.config.yaml`: -Then, all you need to register a new `CloudLogger`: + ```yaml + MeadowCloud: + Enabled: true + ``` -```csharp -public override async Task Initialize() -{ - var cloudLogger = new CloudLogger(); - Resolver.Log.AddProvider(cloudLogger); - ... -} -``` +1. Register a new `CloudLogger` as a logging provider: + + ```csharp + public override async Task Initialize() + { + var cloudLogger = new CloudLogger(); + Resolver.Log.AddProvider(cloudLogger); + ... + } + ``` Once `CloudLogger` is registered, any logging done through `Resolver.Log` automatically gets recorded in Meadow.Cloud. Any logging done while the device is disconnected get stored locally and sent to Meadow.Cloud once a network connected is established. From 7784b4b94448fe270e979ce2591bf13356a66ce5 Mon Sep 17 00:00:00 2001 From: Adam Patridge Date: Sun, 16 Jun 2024 15:20:29 -0600 Subject: [PATCH 12/21] Update getting-started link --- docs/Meadow/Meadow.Foundation/Getting_Started/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Meadow/Meadow.Foundation/Getting_Started/index.md b/docs/Meadow/Meadow.Foundation/Getting_Started/index.md index 854845682..cf9eac497 100644 --- a/docs/Meadow/Meadow.Foundation/Getting_Started/index.md +++ b/docs/Meadow/Meadow.Foundation/Getting_Started/index.md @@ -6,7 +6,7 @@ subtitle: Meadow.Foundation ## Hello, World! -1. [Configure your Meadow development environment](../../Getting_Started/MCUs/F7_Feather/index.md). +1. [Configure your Meadow development environment](../../Getting_Started/index.md). 1. Create a new C# Meadow Application project, name it `HelloPulsy`. 1. Plug the longer leg (anode) of a blue LED into pin `13` and the other leg into `GND`: From 51a0f67ec6faa6f52a54bc936c8438a8500d1789 Mon Sep 17 00:00:00 2001 From: Adam Patridge Date: Sun, 16 Jun 2024 15:42:08 -0600 Subject: [PATCH 13/21] Update SPI sample --- .../Meadow_Basics/IO/Digital/Protocols/SPI/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/SPI/index.md b/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/SPI/index.md index 66dc59f21..6a985fe26 100644 --- a/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/SPI/index.md +++ b/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/SPI/index.md @@ -56,11 +56,11 @@ ISpiBus spiBus = Device.CreateSpiBus(); ## Working with SPI Peripherals -Once the SPI Bus has been created, peripherals can be created by passing in the SPI Bus and the `IDigitalOutputPort` that is connected to the chip select on the peripheral: +Once the SPI Bus has been created, peripherals can be created by passing in the SPI Bus, the `IDigitalOutputPort`, and the bus speed of the SPI bus that is connected to the chip select on the peripheral: ```csharp -IDigitalOutputPort spiPeriphChipSelect = Device.CreateDigitalOutputPort(Device.Pins.D03); -ISpiPeripheral spiPeriph = new SpiPeripheral(spiBus, spiPeriphChipSelect); +IDigitalOutputPort spiCommsChipSelect = Device.CreateDigitalOutputPort(Device.Pins.D03); +ISpiCommunications spiComms = new SpiCommunications(spiBus, spiPeriphChipSelect, new(10_000, Frequency.UnitType.Kilohertz)); ``` ### Peripheral Communication @@ -68,11 +68,11 @@ ISpiPeripheral spiPeriph = new SpiPeripheral(spiBus, spiPeriphChipSelect); Generally, you won't need to handle low-level SPI peripheral communication directly, as the peripheral drivers in Meadow.Foundation expose high level APIs for working with their features. However, if you're creating a new driver, or want to talk to a peripheral directly, there are a number of communications methods exposed via the [`IByteCommunications`](/docs/api/Meadow/Meadow.Hardware/IByteCommunications/) interface, which SPI peripherals implement. Among these are methods to read and write bytes directly to the device as well as read and write to memory registers on the device: ```csharp -spiPeriph.WriteByte(0x01); +spiComms.WriteByte(0x01); ``` These methods are also available via the SPI bus, but require the chip select port of the device to be explicitly passed: ```csharp -spiBus.WriteByte(spiPeriph.ChipSelect, 0x01); +spiBus.Write(spiCommsChipSelect, 0x01); ``` From 72464a42363344d21b406aaf23d4fc28a15f92af Mon Sep 17 00:00:00 2001 From: Adam Patridge Date: Sun, 16 Jun 2024 15:47:09 -0600 Subject: [PATCH 14/21] Fix bus write sample --- docs/Meadow/Meadow_Basics/IO/Digital/Protocols/SPI/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/SPI/index.md b/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/SPI/index.md index 6a985fe26..0ae7370d4 100644 --- a/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/SPI/index.md +++ b/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/SPI/index.md @@ -71,8 +71,8 @@ Generally, you won't need to handle low-level SPI peripheral communication direc spiComms.WriteByte(0x01); ``` -These methods are also available via the SPI bus, but require the chip select port of the device to be explicitly passed: +A similar `Write` method is also available via the SPI bus, but require the chip select port of the device to be explicitly passed: ```csharp -spiBus.Write(spiCommsChipSelect, 0x01); +spiBus.Write(spiCommsChipSelect, new byte[] { 0x01 }); ``` From 735997244bea06a4585ee752e9bab6e90c1fd7aa Mon Sep 17 00:00:00 2001 From: Adam Patridge Date: Sun, 16 Jun 2024 15:51:08 -0600 Subject: [PATCH 15/21] Update sample to new I2cCommunications API --- .../Meadow_Basics/IO/Digital/Protocols/I2C/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/I2C/index.md b/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/I2C/index.md index 816362ad5..bc5d21824 100644 --- a/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/I2C/index.md +++ b/docs/Meadow/Meadow_Basics/IO/Digital/Protocols/I2C/index.md @@ -62,10 +62,10 @@ II2cBus i2cBus = Device.CreateI2cBus(); ## Working with I2C Peripherals -Once the I2C Bus has been created, peripherals can be created by passing in the I2C Bus and the address of the peripheral: +Once the I2C Bus has been created, you create a communications object to send data through the I2C Bus on a specific address: ```csharp -II2cPeripheral i2cPeripheral = new I2cPeripheral(i2cBus, 39); +II2cCommunications i2cComms = new I2cCommunications(i2cBus, 39); ``` ### Peripheral Communication @@ -73,11 +73,11 @@ II2cPeripheral i2cPeripheral = new I2cPeripheral(i2cBus, 39); Generally, you won't need to handle low-level I2C peripheral communication directly, as the peripheral drivers in Meadow.Foundation expose high level APIs for working with their features. However, if you're creating a new driver, or want to talk to a peripheral directly, there are a number of communications methods exposed via the [`IByteCommunications`](/docs/api/Meadow/Meadow.Hardware/IByteCommunications/) interface, which I2C peripherals implement. Among these are methods to read and write bytes directly to the device as well as read and write to memory registers on the device: ```csharp -i2cPeripheral.WriteByte(0x01); +i2cComms.Write(0x01); ``` These methods are also available via the I2C bus, but require the address of the device to be explicitly passed: ```csharp -i2cBus.WriteByte(i2cPeripheral.Address, 0x01); +i2cBus.Write(i2cComms.Address, new byte[] { 0x01 }); ``` From e767b6b689d4e188797211c38738246f6f1d03b0 Mon Sep 17 00:00:00 2001 From: Adam Patridge Date: Sun, 16 Jun 2024 16:14:23 -0600 Subject: [PATCH 16/21] Add cable/power warnings --- docs/Meadow/Getting_Started/Deploying_Meadow.OS/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/Meadow/Getting_Started/Deploying_Meadow.OS/index.md b/docs/Meadow/Getting_Started/Deploying_Meadow.OS/index.md index d01a1c7c5..003f7c145 100644 --- a/docs/Meadow/Getting_Started/Deploying_Meadow.OS/index.md +++ b/docs/Meadow/Getting_Started/Deploying_Meadow.OS/index.md @@ -7,6 +7,10 @@ subtitle: Flashing the Meadow with the latest OS via Meadow.CLI When you receive your Meadow board, it will need to have the latest Meadow.OS uploaded, or _flashed_, to it. +> NOTE: Communicating with the Meadow board for updates and deployments requires a quality USB cable with data lines. Some USB charging cables only have power lines connected internally or have poor construction that may not properly support communication. Power-only cables will not work for communicating with a device. And poorly constructed cables may fail during various updating and deploying attempts. Make sure to find a quality USB cable with data lines if your Meadow device is not recognized or communication errors occur. +> +> Additionally, if you have your Meadow device connected through a USB hub without a dedicated power supply, it may not provide enough power to the device. In this case, connect the Meadow device directly to your computer. + From b9304196ca58ce85c3d368017c20722815960e15 Mon Sep 17 00:00:00 2001 From: Adam Patridge Date: Sun, 16 Jun 2024 16:27:13 -0600 Subject: [PATCH 17/21] Update to send users to getting-started directly --- docs/Meadow/Getting_Started/Setup/index.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/Meadow/Getting_Started/Setup/index.md b/docs/Meadow/Getting_Started/Setup/index.md index 1672f3f3e..d6dffddb1 100644 --- a/docs/Meadow/Getting_Started/Setup/index.md +++ b/docs/Meadow/Getting_Started/Setup/index.md @@ -4,11 +4,4 @@ title: Setup subtitle: Guides and documentation for Meadow --- -# Configuring the Meadow Build Environment - -1. [Connect Meadow to the ST-Link V2](stlink/) - * Configure Your Development Environment: - * [macOS](macos/) - * [Windows](Windows/) - -## [Next - Deploy Meadow OS](/Meadow/Getting_Started/Deploying_Meadow%2EOS/) \ No newline at end of file +This content has [moved](/Meadow/Getting_Started/). From 52cd5abdbfc872a64be55e2d1a52c650aef79a4e Mon Sep 17 00:00:00 2001 From: Adam Patridge Date: Mon, 24 Jun 2024 12:37:00 -0600 Subject: [PATCH 18/21] Add note on hole clearance --- docs/Meadow/Getting_Started/Assemble_Meadow/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Meadow/Getting_Started/Assemble_Meadow/index.md b/docs/Meadow/Getting_Started/Assemble_Meadow/index.md index 5fe382f39..d348cf6e9 100644 --- a/docs/Meadow/Getting_Started/Assemble_Meadow/index.md +++ b/docs/Meadow/Getting_Started/Assemble_Meadow/index.md @@ -43,7 +43,7 @@ Meadow has battery connector on the right side of the device. For this reason, y ![Breadboard, Protoboard and Meadow](./MeadowDev_Places.jpg) -Remove the plastic sticker cover under the breadboard and stick it to the protoboard as firm and straight as possible. +Remove the plastic sticker cover under the breadboard and stick it to the protoboard as firm and straight as possible. If you plan to use the outer-most holes to mount your Meadow kit to something else, make sure to keep the holes clear with enough room to add screws or standoffs. ![Protoboard with breadboard mounted and Meadow adjacent with mounting hardware.](./MeadowDev_Breadboard.jpg) From d749a7d051d12a537abf015c2c1221a983b1434d Mon Sep 17 00:00:00 2001 From: Eduardo Menezes Date: Thu, 27 Jun 2024 13:27:28 -0300 Subject: [PATCH 19/21] Minor fix on Ethernet config sample --- docs/Meadow/Meadow.OS/Networking/index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/Meadow/Meadow.OS/Networking/index.md b/docs/Meadow/Meadow.OS/Networking/index.md index 2d8b0cb5d..da96aff62 100644 --- a/docs/Meadow/Meadow.OS/Networking/index.md +++ b/docs/Meadow/Meadow.OS/Networking/index.md @@ -124,17 +124,17 @@ If you're using an [Dual, Switching Ethernet Add-on module](https://store.wilder Network: Interfaces: - Name: Ethernet - UseDHCP: false - IPAddress: 192.168.1.60 - NetMask: 255.255.255.0 - Gateway: 192.168.1.254 -# - Name: Ethernet -# UseDHCP: true + UseDHCP: true + # IPAddress: 192.168.1.60 + # NetMask: 255.255.255.0 + # Gateway: 192.168.1.254 DefaultInterface: Ethernet ... ``` -Optionally you can set the `UseDHCP: true` to get an IP Address automatically. If `DefaultInterface` is not set on the config file, it will default to WiFi. +Optionally you can set the `UseDHCP: false` to use an static IP Address, in this case, please configure your `IpAddress`, `NetMask`, and `Gateway` correctly, ensuring the `IPAddress` is within your local network and not already in use. + + If `DefaultInterface` is not set on the config file, it will default to WiFi. From 439082756bb94b6007a5e9e3a02bf4c3c37c08fd Mon Sep 17 00:00:00 2001 From: Adam Patridge Date: Thu, 27 Jun 2024 15:42:24 -0600 Subject: [PATCH 20/21] Update index.md --- docs/Meadow/Meadow.OS/Networking/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Meadow/Meadow.OS/Networking/index.md b/docs/Meadow/Meadow.OS/Networking/index.md index da96aff62..2d6840dec 100644 --- a/docs/Meadow/Meadow.OS/Networking/index.md +++ b/docs/Meadow/Meadow.OS/Networking/index.md @@ -132,9 +132,9 @@ Network: DefaultInterface: Ethernet ... ``` -Optionally you can set the `UseDHCP: false` to use an static IP Address, in this case, please configure your `IpAddress`, `NetMask`, and `Gateway` correctly, ensuring the `IPAddress` is within your local network and not already in use. +Optionally you can set the `UseDHCP: false` to use an static IP Address. In this case, please configure your `IpAddress`, `NetMask`, and `Gateway` correctly, ensuring the `IPAddress` is within your local network and not already in use. - If `DefaultInterface` is not set on the config file, it will default to WiFi. +If `DefaultInterface` is not set on the config file, it will default to WiFi. From 3d350bda477b395eebb9031188eaebf3beff4915 Mon Sep 17 00:00:00 2001 From: Jorge Ramirez Date: Thu, 11 Jul 2024 22:14:32 -0700 Subject: [PATCH 21/21] Add release notes for 1.12.8.0 --- docs/Meadow/Release_Notes/v1/index.md | 35 +++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/docs/Meadow/Release_Notes/v1/index.md b/docs/Meadow/Release_Notes/v1/index.md index 41a3cfa8d..e7b171359 100644 --- a/docs/Meadow/Release_Notes/v1/index.md +++ b/docs/Meadow/Release_Notes/v1/index.md @@ -10,6 +10,41 @@ subtitle: Release Notes * [Meadow.CLI](/Meadow/Meadow_Tools/Meadow_CLI/) * [Meadow.OS](/Meadow/Getting_Started/Deploying_Meadow%2EOS/) +## v1.12.8.0 + +### Meadow.OS + +* This is a managed stack release only. No OS changes. + +### Meadow.Core + +* Added WiFi scanning support to Meadow.Linux +* Bug fixes to I2C reads in Meadow.Linux +* Improved app crash logging +* Bug fixes in F7 PWMs +* Added new `IApp` pattern for platforms like ProjectLab +* Bug fix in app.config parser +* Bug fixes in MicroLayout (positioning inside a parent) +* Bug fix in SpiComms ReadRegister +* Bug fixes in Gnss parsing +* Improved network adapter events for wired, cell, and wifi +* Added NTP support to Cell adapter + +#### Breaking changes + +* PWMs now use Units for Duration and Frequency instead of the ambiguous float +* Renamed [Ft232h](https://www.nuget.org/packages/Meadow.Foundation.ICs.IOExpanders.Ft232h/) nuget package to [Ftxxxx](https://www.nuget.org/packages/Meadow.Foundation.ICs.IOExpanders.Ftxxxx) + +### Meadow.Foundation + +* Added `JsonPropertyName` to `MicroJson` +* Added support for `TimeSpan`, nullables and `List` to `MicroJson` +* Added `ResistiveTankLevelSender` + +#### Breaking changes + +* [Servos](https://www.nuget.org/packages/Meadow.Foundation.Servos) have been refactored, fixed and improved. The previous Servo API was both confusing and likely not working. + ## v1.12.2 ### Meadow.OS