TugboatQA / docs

Tugboat Docs
https://docs.tugboat.qa
MIT License
9 stars 18 forks source link

Add examples to environment variables. #381

Closed KeyboardCowboy closed 4 months ago

KeyboardCowboy commented 8 months ago

I was struggling to figure out exactly what value each ENV var would produce, so I created a PR that dumped them all out as examples. With those, I thought it might be helpful to add those examples to the docs. I chose a table layout for readability.

Here's how this is working: I wanted to have all the example values come from the same preview so there was consistency as people read down the list. To make updating the variables less of a headache in the future for this purpose, I wrote a node script to read a yaml file containing the variables with their headings and descriptions and generate the markup needed for the actual document. Now, if we want to add/remove/update the docs for an environment variable, you do that in the .tugboat/env-vars.yml file. The process looks like this:

  1. Edit the .tugboat/env-vars.yml file
  2. Push to GitHub and create a PR.
  3. Have Tugboat build the preview with a base preview.
  4. Go to https://[preview-subdomain].tugboatqa.com/vars.md and copy the markdown.
  5. Paste it into the doc at /content/reference/environment-variables.md
  6. Commit and push again.
  7. Review the PR for merging.

To Merge

I created a branch called main-node to use as the base for my preview. That branch should be merged first, then this one can be merged into main as well.

q0rban commented 7 months ago

@KeyboardCowboy I like this a lot! What else do you need from us to move this forward? You might try running the yarn lint-fix command locally to fix any linting errors.

KeyboardCowboy commented 7 months ago

Thanks, @q0rban! This is just one section, so I'd like to apply the table to the variables in the other sections as well before we merge it. I'll see if I can get back on it next week.