Based on discussion in #19408, update the documentation to specify that `:pwsh` must be passed explicitly and that it will translate to a "powershell" argument, as is currently supported by Go's common `github.com/spf13/cobra` module and Rust's common `clap` (with `clap_complete`) crate.
Some RubyDoc URL fragments in the Formula Cookbook documentation
include an equals sign (`%3D`) but the `id` attributes in the current
RubyDoc HTML don't include the equals sign, so the documentation CI
job is failing with errors like `External link
https://rubydoc.brew.sh/Formula#revision=-class_method failed:
https://rubydoc.brew.sh/Formula exists, but the hash
'revision=-class_method' does not`. This updates the URLs to remove
`%3D` accordingly.
- At the AGM we formed an ad-hoc documentation working group.
- One of our ideas was that we should have a last reviewed date for
documentation, so that we can periodically implement a review
mechanism (GitHub Actions posts to Slack for a regular documentation
outdatedness check?) to track how old docs are and ensure they're
still relevant.
- This is a first step towards that goal, by adding a `last_review_date`
to the metadata of all docs with a date of earlier than Homebrew's
inception because everything needs reviewing so that we start from a
good base!
Document the specific case, where your program writes an error to stderr
that needs to be checked in a test (e.g., using `assert_match` and
`shell_output`):
* https://github.com/Homebrew/brew/issues/5149
Co-authored-by: Mike McQuaid <mike@mikemcquaid.com>
- We don't need this blanket enabled, we only have a few docs where it actually matters that there's a description, it's just cruft having to invent descriptions.
- Yes, we have yet another `.rubocop.yml` but in-line exclusions in
`<span class="display:none;">` in the Markdown seemed more ugly.
- This needed tweaks to `brew style` to make it read the new config
file when we're scanning docs.
- Blocks should open with `do` and close with `end`.
- `...` is not valid Ruby syntax, so comment it out so that the user
knows that it's a placeholder for "other things here".
- Reword the "header line details" in `Cask-Cookbook` otherwise RuboCop
crashes even with an `end` because of the empty block. There was
already an example of a valid header line in the first code block on
the page, so it's not a big loss.
In https://github.com/Homebrew/homebrew-core/pull/157910 we discussed
some improvements to docs on setting up gems. THis is an attempt at some
docs for that.
If someone can help with pip docs for this I'll add it too.
Signed-off-by: Phil Dibowitz <phil@ipom.com>
v0.13 of the `markdownlint` gem just got released and it has
a few new rules which are docs ended up failing. This fixes
those linter errors so that CI is no longer red.
Rules:
MD055 - Tables: Each row must start and end with a '|'
MD057 - Tables: In the second row every column must have at least '---',
possibly surrounded with alignment ':' chars
This is more in keeping with the other DSL methods and Ruby
convention along with the fact that these socket names are
just used internally by launchd.
