docs-build first pass

[briantist]

Description

Adding docs builds on push and PR. There's no publish step yet for these, so this does the following for now:

• on push: ensures docs can be built without errors
• on PR:
  • ensures docs build without errors
  • performs a lenient build on both the PR base and target, compares them, and if there are differences, posts a comment on the PR highlighting the differences
  • when a publishing step is included (future), the comment can include links to these pages
  • the built docsite can be downloaded from the build artifacts to be inspected locally

How Has This Been Tested?

UPDATE on below:

• PR flows tested in #41
• Push tested in https://github.com/lowlydba/lowlydba.sqlserver/actions/runs/2045703922

---

The push workflow only triggers on pushes to main, and the PR workflow uses the pull_request_target event which means that the workflow itself is always loaded from the target branch, not from the PR contents.

As a result, the push workflow can't be tested without either merging first, or changing the target branch in the PR and then changing it back.

For pull_request_target workflows, the PR introducing it or changing it must be pushed to a branch on the main repo, not on a fork, and then a test PR can be opened (from a fork or the main repo) against that branch, in order to trigger the workflow.

So I'm putting this up as is, not from a fork, and I will open a test PR for the latter case.

I may also mess with the branch filter on the push workflow to try to test that.

Types of changes

• [X] New feature (non-breaking change which adds functionality)

Checklist:

• [X] I have read/followed the CONTRIBUTING document.
• [X] I have read/followed the PR Quick Start Guide # TODO: update with link to published doc
• [X] I have added tests to cover my changes or they are N/A.
• [X] New module options/parameters include a version_added property.

[codecov-commenter]

Codecov Report

Merging #40 (16f5222) into main (613dbde) will increase coverage by 5.02%. The diff coverage is n/a.

@@             Coverage Diff             @@
##             main       #40      +/-   ##
===========================================
+ Coverage   94.97%   100.00%   +5.02%     
===========================================
  Files          33        17      -16     
  Lines        1014        53     -961     
===========================================
- Hits          963        53     -910     
+ Misses         51         0      -51     

Impacted Files	Coverage Δ
plugins/modules/login.ps1
plugins/modules/sp_configure.ps1
plugins/modules/agent_job_category.ps1
plugins/modules/agent_job_step.ps1
plugins/modules/nonquery.ps1
plugins/modules/rg_workload_group.ps1
plugins/modules/traceflag.ps1
plugins/modules/memory.ps1
plugins/modules/agent_job_schedule.ps1
plugins/module_utils/_SqlServerUtils.psm1
... and 6 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 613dbde...16f5222. Read the comment docs.

[briantist]

PR build success screenshot:

[briantist]

Right now we have it removing the PR comment on close. When there's a publish, I would change it to updating the comment on close (different messages for whether or not the PR was merged). When merged, we can give a link to the "main" published docs for example.

[briantist]

41 can be reopened if you want to see the build/comment happen live.

Also highly recommending downloading the artifact so you can browse the generated site locally and take a look :)

[lowlydba]

😍 Very cool! Super cool to see the docs after refactoring so many of these python docs.

[briantist]

😍 Very cool! Super cool to see the docs after refactoring so many of these python docs.

Totally! It can be easy to miss things or make mistakes without being able to see the rendered versions, that's what drove me to start this stuff.

I haven't gotten around to working out a GitHub Pages publishing target, but from early research I think it'll be straightforward. I do plan to make a reusable workflow for that in the docs build repo (like I have for Surge.sh hosting), but if you're willing, this repo could be the place where I develop that and work out the kinks, I don't think it'll take much.

[briantist]

some underlying docs build stuff was fixed, so updated this too, I think it's ready to go!

[briantist]

@lowlydba any objections?

[github-actions[bot]]

Docs Build 📝

Thank you for contribution!✨

This PR has been merged and the docs are now incorporated into main.