Skip to content

Use Quarto profiles for rendering the site on GitHub and locally#372

Merged
nrichers merged 3 commits intomainfrom
nrichers/sc-6407/switch-quarto-over-to-project-profiles-per
Sep 17, 2024
Merged

Use Quarto profiles for rendering the site on GitHub and locally#372
nrichers merged 3 commits intomainfrom
nrichers/sc-6407/switch-quarto-over-to-project-profiles-per

Conversation

@nrichers
Copy link
Copy Markdown
Collaborator

@nrichers nrichers commented Sep 17, 2024

Internal Notes for Reviewers

This PR enables our GitHub workflows and local Makefile to use Quarto profiles with Heap tracking for:

  • Development (PR previews)
  • Staging
  • Production

Quarto profiles enable us to remove environment-specific rendering instructions out of GitHub branches which is a prerequisite to simplifying our merge strategy.

Tracking for these profiles matches our environments on Heap:

Environment ID
Development 3544910167
Staging 3193732798
Production 2282992095

Development environment

quarto preview --profile development

image

Staging environment

quarto preview --profile staging

image

Production environment

quarto preview --profile production

image

No tracking

quarto preview

image

External Release Notes

@nrichers nrichers added infrastructure Docs infra changes internal Not to be externalized in the release notes labels Sep 17, 2024
@github-actions
Copy link
Copy Markdown
Contributor

A PR preview is available: Preview URL

@github-actions
Copy link
Copy Markdown
Contributor

A PR preview is available: Preview URL

@nrichers nrichers changed the title Move Heap info its own environment folder Use Quarto profiles for rendering the site on GitHub and locally Sep 17, 2024
@nrichers nrichers requested a review from validbeck September 17, 2024 00:42
@github-actions
Copy link
Copy Markdown
Contributor

PR Summary

This pull request introduces several enhancements to the documentation build and deployment process:

  1. Quarto Render Profiles: The quarto render command is now executed with specific profiles (development, staging, production) across various GitHub Actions workflows and Makefile targets. This change ensures that the appropriate configuration is used for different environments.

  2. Environment-Specific Configurations: New configuration files (_quarto-development.yml, _quarto-staging.yml, _quarto-production.yml) have been added to the site directory. These files include environment-specific settings, such as including different HTML headers for each environment.

  3. Heap Analytics Integration: A new HTML file (heap-staging.html) has been added to the site/environments directory, which includes a script for loading Heap Analytics in the staging environment. Similar files for development and production environments are also introduced but are currently empty.

Test Suggestions

  • Verify that the documentation site builds successfully in the development, staging, and production environments using the respective profiles.
  • Check that the correct HTML headers are included in the generated documentation for each environment.
  • Ensure that the Heap Analytics script is correctly loaded and executed in the staging environment.
  • Test the deployment process to S3 and CloudFront for all environments to ensure that the changes do not break the deployment pipeline.

@nrichers nrichers mentioned this pull request Sep 17, 2024
14 tasks
Copy link
Copy Markdown
Collaborator

@validbeck validbeck left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good! Only q is, is the development profile linked to the PR previews in docs-demo?

@nrichers
Copy link
Copy Markdown
Collaborator Author

Looks good! Only q is, is the development profile linked to the PR previews in docs-demo?

Yes, we render the site for PR previews with --profile development. See https://github.com/validmind/documentation/pull/372/files#diff-97e4422bf78b64c199ffc642cb458be76ad2bd30b54a40c85846cfc7f2d35cebR35 for the details.

@nrichers
Copy link
Copy Markdown
Collaborator Author

Looks good! Only q is, is the development profile linked to the PR previews in docs-demo?

Oh, there's an even better way to show you! Since this PR has a preview, we can verify in there that the right profile is being used:

image

3544910167 maps to our development environment, so this is correct.

@nrichers nrichers merged commit 10e2fc6 into main Sep 17, 2024
@nrichers nrichers deleted the nrichers/sc-6407/switch-quarto-over-to-project-profiles-per branch September 17, 2024 18:03
@nrichers
Copy link
Copy Markdown
Collaborator Author

Staging site deployed and also shows the correct Heap tracking — 3193732798:

image

nrichers added a commit that referenced this pull request Sep 21, 2024
* Add staging docs site deploy and update prod deploy (#309)

* Add new staging docs site deploy action and workflow

* Change to PR branch for testing

* Change to PR branch for testing, take 2

* Add quarto render steps to staging and prod workflows

* Minor wording fix

* Minor wording tweaks

* Change to prod site for testing

* Fix path issue in aws command, revert to correct branches

* Remove some GitHub variables

* Switch staging deploy to new AWS access keys

* Switch to PR branch for testing

* Fix duplicate names

* Update bucket region info

* Formatting

* Update Cloudfront info for staging and debug paths

* More path debugging

* More path debugging

* Fix deploy paths & remove debugging info

* Switch back to staging branch

* Change to PR branch for testing

* Change back to staging branch

* Change to PR branch and docs-demo bucket for testing

* Change back to prod branch and prod bucket

* Delete site/_site directory in staging (#326)

* Revamped Model Activity docs (#315)

* Filter activity setup

* Simplified some inline links

* Draft of edited unless-format footnotes

* Edited unless-format for Model Activity & Document Overview

* Edited unless-format for Submit for approval

* Edited unless-format for Assess compliance

* Edited unless-format for Work with model findings

* Fixed broken links in single-source

* Edits based on what is available locally

* Final tweaks

* Added single-source template

* Update README.md

* Update README.md

* Update site/guide/configuration/manage-your-profile.qmd

Co-authored-by: Nik Richers <[email protected]>

* Update site/guide/configuration/manage-your-profile.qmd

Co-authored-by: Nik Richers <[email protected]>

* Bolded compliance assessments

---------

Co-authored-by: Nik Richers <[email protected]>

* Release notes for Sept 9 2024 (#329)

* Draft of new release notes

* Edited validation guidelines release

* Draft -need to edit bug fixes

* Why did it not commit all files??

* Final tweaks to body

* Summary added

* Grammar??

* Removed extra documentation as requested

* Removed bug fixes

* My brain is not on today, typo

* Only running the PR previews bot when a PR is ready for review (#330)

* Can we make it only run once let's see

* Updated to review_requested

* Modify make python-docs to support rendering online (#336)

* Modify make python-docs to store files in site folder

* Add python-docs to source

* Delete .github/workflows/render-site.yaml (#344)

* Investigate listing page issue  (#334)

* Remove echoing to log file

* Add quarto check to workflow

* Add TinyTex install

* Experiment by removing tabset

* Remove TinyTex install

* Re-add tabset, try individual file embeds

* Try changing wildcard embed

* Try different wildcard embed

* Undo workflow changes

* Fix Heap embeds for docs sites — `main` branch (#339)

* Remove production Heap embed

* Re-add Heap file for development

* Fix heap embeds for docs sites — staging branch (#340)

* Doc: Archive and delete inventory models (#351)

* Delete model findings draft

* Tweaks to project > model

* Draft for Archive & delete models

* Oops carried changes from a working branch instead of main, reverting

* Tweaking wording

* Indecisive about wording today

* Added archive & delete to sidebar

* Final tweaks based on what's on staging

* Typo

* Tired, tweaks

* Update site/guide/model-inventory/archive-delete-models.qmd

Co-authored-by: Nik Richers <[email protected]>

---------

Co-authored-by: Nik Richers <[email protected]>

* Revamped model findings docs for attachments (#352)

* Draft

* More fiddling

* Fiddling

* Link tweaks

* More project tweaks

* Editing based on demo

* Created new Working with model findings landing

* 1st pass of broken links

* 2nd pass of broken links

* Summary drafts

* Tweaks

* More tweaks

* Adjustments for prod

* Adding deletion after discussion

* Images

* Removed commented out indications for required fields

* New all model findings image

* Pulling in latest changes from PR184 (#350)

* Pulled in latest test descriptions Sept 03 2024

* Example retrieval for process docs

* Delete finding docs update (#355)

* Delete finding update, also python docs from main?

* Changed to Add and manage model findings

* Moved activity to model inventory & adjusted pages (#358)

* Moved activity to model inventory & adjusted pages

* Missed a link apparently thanks workflow

* Missed an external link

* Training updates related to creating videos (#227)

* Update training title slides

* Move training into navbar

* Fix glossary entry

* Rename training overview file

* Fix links to old training filename

* Minor styling tweaks before recording videos

* Add instruction to verify workflow

* Clean up

* Update title

* Comment out banner

* Re-added announcement, but for our technical brief

* lil divider for funsies

---------

Co-authored-by: Beck <[email protected]>

* Clarified style guidelines for links & training (#363)

* Inline link & training draft

* Edits to footnotes

* Example images

* Footnotes

* Tweaks

* Typos

* Update site/about/contributing/style-guide/conventions.qmd

Co-authored-by: Nik Richers <[email protected]>

* Edited the other front matter ref

---------

Co-authored-by: Nik Richers <[email protected]>

* Adding new ValidMind colors & logo (#366)

* Start adding updated ValidMind colors & logo

* Bit more of that lovely green

* Prereq tweak

---------

Co-authored-by: Beck <[email protected]>

* Update workflows to trigger on workflow_run (#368)

* Update workflows to enable workflow_run

* Experiment with workflow_dispatch

* Update README.md (#369)

* Use Quarto profiles for rendering the site on GitHub and locally (#372)

* Move Heap info its own environment folder

* Add Quarto profiles

* Add profiles for more development builds

* Docs site audit accuracy tone review — Guides p1 (#377)

* Edits to swap docs templates

* Added ongoing monitoring to swap templates

* Cleaned up guides.qmd

* Cleaned up log-in-to-validmind.qmd

* Cleaned up set-up-your-organization.qmd

* Cleaned up configure-google... .qmd

* Cleaned up managing-users .qmd

* Cleaned up manage-users.qmd

* Cleaned up manage-groups.qmd

* Cleaned up manage-roles.qmd

* Cleaned up manage-your-profile.qmd

* Cleaned up customize-your-dashboard.qmd

* Cleaned up working-with-model-workflows.qmd

* Cleaned up customize-model-lifecycle-statuses.qmd

* Cleaned up set-up-model-workflows.qmd

* Cleaned up working-with-model-inventory.qmd

* Cleaned up register-models-in-inventory.qmd

* Cleaned up customize-model-inventory-layout.qmd

* Cleaned up edit-model-inventory-fields.qmd

* Cleaned up view-model-activity.qmd

* Cleaned up configure-model-interdependencies.qmd

* Cleaned up manage-model-inventory-fields.qmd

* Tweaks for model stage columns

* Cleaned up view-documentation-templates.qmd

* Cleaned up customize-documentation-templates.qmd

* Cleaned up swap-documentation-templates.qmd

* Cleaned up assign-documentation-section-statuses.qmd

* Cleaned up submit-for-approval.qmd

* Cleaned up export-documentation.qmd

* Cleaned up collaborate-with-others.qmd

* Project > Model updates

* Cleaned up manage-validation-guidelines.qmd

* Cleaned up pereparing-validation-reports.qmd

* Cleaned up review-model-documentation.qmd

* Cleaned up assess-compliance.qmd

* Cleaned enable-monitoring.qmd

* Cleaned review-monitoring-results.qmd

* Final tweaks

* Captions added to configuration/

* Captions added to model-workflows/

* Captions added to model-inventory/

* Captions added to model-documentation/

* Captions added to model-validation/

* Captions added to monitoring/

* Update site/guide/configuration/configure-aws-privatelink.qmd

Co-authored-by: Nik Richers <[email protected]>

* Update site/guide/model-documentation/collaborate-with-others.qmd

Co-authored-by: Nik Richers <[email protected]>

* Quick tweak

---------

Co-authored-by: Nik Richers <[email protected]>

* Revamped View reports (#409)

* Draft edits

* New images

* Setup for overview of data

* Final revamp, +customizing model findings view

* Final tweaks

* Update site/guide/model-validation/view-filter-model-findings.qmd

Co-authored-by: Nik Richers <[email protected]>

* Adjusted casing for report widgets

---------

Co-authored-by: Nik Richers <[email protected]>

* Updated Work with content blocks (#390)

* Draft of metric over time blocks info

* Draft for toolbar overview

* Adjusting images

* Edits for toolbar

* Quick tweak

* Quick single source

* Make training slides more photogenic (#412)

* Add docs.validmind.ai/training redirect

* Update backgrounds, remove slide numbering, add slide links

* Documented user registration process (#410)

* Draft new pages

* New files

* Draft for independent signup

* Last save for the day

* Simplifying some stuff

* Accept invitation draft

* Layout tweaks

* Accept invite wip

* Register done for now

* New registration variable

* Applied new variable across site

* Final tweaks

* Quick tweak

* Cropped images

* Update site/guide/configuration/register-with-validmind.qmd

Co-authored-by: Nik Richers <[email protected]>

* Update site/guide/configuration/register-with-validmind.qmd

Co-authored-by: Nik Richers <[email protected]>

* Update site/guide/configuration/register-with-validmind.qmd

Co-authored-by: Nik Richers <[email protected]>

* Update site/guide/configuration/register-with-validmind.qmd

Co-authored-by: Nik Richers <[email protected]>

* Tweaks

---------

Co-authored-by: Nik Richers <[email protected]>

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Beck <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

infrastructure Docs infra changes internal Not to be externalized in the release notes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants