* Reapply dropped commit in https://github.com/Homebrew/brew/pull/16643
* Change bindings example as `protobuf` no longer has any
* Remove `name "foo"` in example
* Replace `Language::Python.setup_install_args` example with `pip`
* Add some hints for CMake and autotools scripts given common issue of
incorrect Python selection due to allowing multiple Python deps
* Add note that `.pth` files should be avoided due to contamination
Co-authored-by: Eric Knibbe <enk3@outlook.com>
Signed-off-by: Michael Cho <michael@michaelcho.dev>
- 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.
Adjust various maintainer and contributor-focused documents after
recent maintainer conversations and generally anything I noticed was
wrong or outdated as I went through these.
Anywhere we can use `blob/master` we can use `blob/HEAD` instead. This
will make life easier if we ever rename our default branch in future
(once/if Git and GitHub provides the necessary tooling to do so).
When the line was switched to the more explicit
`virtualenv_create(libexec, "python3")` the package installed with any issues.
Arguably, I am not as comfortable as I would like with Homebrew's relationship with Python, so maybe this reveals a larger underlying issue or there was a mistake within the original Formula.
The formula is hosted [here](https://github.com/saulpw/homebrew-vd).
```
Last 15 lines from /Users/anja/Library/Logs/Homebrew/visidata/14.pip:
Removing source in /private/tmp/pip-req-build-CH6VRn
visidata requires Python '>=3.4' but the running Python is 2.7.10
Exception information:
Traceback (most recent call last):
File "/usr/local/Cellar/visidata/1.2/libexec/lib/python2.7/site-packages/pip/_internal/basecommand.py", line 228, in main
status = self.run(options, args)
File "/usr/local/Cellar/visidata/1.2/libexec/lib/python2.7/site-packages/pip/_internal/commands/install.py", line 291, in run
resolver.resolve(requirement_set)
File "/usr/local/Cellar/visidata/1.2/libexec/lib/python2.7/site-packages/pip/_internal/resolve.py", line 103, in resolve
self._resolve_one(requirement_set, req)
File "/usr/local/Cellar/visidata/1.2/libexec/lib/python2.7/site-packages/pip/_internal/resolve.py", line 262, in _resolve_one
check_dist_requires_python(dist)
File "/usr/local/Cellar/visidata/1.2/libexec/lib/python2.7/site-packages/pip/_internal/utils/packaging.py", line 55, in check_dist_requires_python
'.'.join(map(str, sys.version_info[:3])),)
UnsupportedPythonVersion: visidata requires Python '>=3.4' but the running Python is 2.7.10
```
Auditing a formula with this structure (plus a `desc` statement)
results in an audit warning:
> * C: 12: col 3: `include` (line 12) should be put before `desc` (line 2)
Bare URLs are auto-linked on GitHub but not on docs.brew.sh, so I added
angle brackets around them where appropriate. Also converted
Markdown-linked URLs for clarity.
GitHub now nicely generates a documentation site for us at
http://brew.sh/brew based on our docs folder. Optimise the output of
this and the GitHub docs directory for readability and the various user
groupings.
