Skip to content

Commit

Permalink
Merge remote-tracking branch 'origin/main' into dlaliberte-autolinks-…
Browse files Browse the repository at this point in the history 
…11-01
  • Loading branch information
@dlaliberte
dlaliberte committed Nov 10, 2023
2 parents 5af6cbc + 7884fd2 commit efc762a
Show file tree
Hide file tree
Showing 5 changed files with 102 additions and 48 deletions.
2 changes: 0 additions & 2 deletions .github/workflows/ci.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,6 @@ jobs:
fail-fast: true
matrix:
python-version:
- '3.7'
- '3.8'
- '3.9'
- '3.10'
- '3.11'
Expand Down
6 changes: 3 additions & 3 deletions bikeshed/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,10 @@ def verify_python_version() -> None:
)
sys.exit(1)

if sys.version_info < (3, 7):
if sys.version_info < (3, 9):
print(
"""Bikeshed now requires Python 3.7; you are on {}.
For instructions on how to set up a pyenv with 3.7, see:
"""Bikeshed now requires Python 3.9 or higher; you are on {}.
For instructions on how to set up a pyenv with 3.9, see:
https://speced.github.io/bikeshed/#installing""".format(
platform.python_version(),
),
Expand Down
71 changes: 50 additions & 21 deletions docs/index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ has a few (pretty easy) steps.

### `python3` ### {#install-py3}

Bikeshed requires Python 3.7 or later.
Bikeshed requires Python 3.9 or later.
(It's currently tested up to 3.11.)

To tell what version you have,
Expand All @@ -102,7 +102,7 @@ run:
python3 --version
```

If it reports 3.7 or later, you're fine.
If it reports 3.9 or later, you're fine.

If it's earlier, you'll need to update your local Python version.
There are several ways to do so,
Expand All @@ -114,12 +114,9 @@ It also links to the auto-installer, which can make things even easier.
Windows users have slightly different instructions,
but it links to a windows fork as well.

Note that the final install step currently installs 3.7.8;
that's fine, go ahead and follow it.

If you know your way around pyenv already,
feel free to do what you're used to here.
Otherwise, it's usually easiest to set up 3.7 as your "default" Python:
Otherwise, it's usually easiest to set up 3.10 as your "default" Python:

```bash
pyenv versions
Expand All @@ -128,15 +125,12 @@ pyenv versions
will list what versions exist, and then

```bash
pyenv global 3.7.0
pyenv global 3.10.4
```

will set 3.7.0 as your "global" version, used by default.
will set 3.10.4 as your "global" version, used by default.
(Substitute in whatever the name of the version you saw in `versions` was.)

(Alternately, use a 3.10 or 3.11 version,
as many Python programs now assume these versions.)

### `pipx` ### {#install-pipx}

Installing packages globally is usually a bad (and sometimes insecure!) idea.
Expand Down Expand Up @@ -165,15 +159,15 @@ Assuming the prereqs (above) are satisfied,
installation is trivial:

```bash
pipx install bikeshed && bikeshed update
pipx install bikeshed
```

When this is completed, Bikeshed should be installed,
and the `bikeshed` command should work in your shell.

Note: If this is your first time running `pipx`,
you might get a message complaining about your PATH variable,
and the `bikeshed update` command will fail.
and Bikeshed's attempt to update its data files will fail.
If so, follow `pipx`'s instructions,
then run `bikeshed update` again.

Expand All @@ -187,11 +181,22 @@ bikeshed
Remember to update Bikeshed regularly by running:

```bash
pipx upgrade bikeshed && bikeshed update
pipx upgrade bikeshed
```

See [[#updating-bikeshed]] for more details.

You can also manually refresh Bikeshed's datafiles by running:

```bash
bikeshed update
```

But this will run automatically
whenever you use Bikeshed
if your data files are more than a few days old,
so it usually shouldn't be necessary.

Note: If you're on a Mac,
`bikeshed update` might fail with some errors about certificates.
This is a known issue with the version of Python 3.7 shipped with XCode,
Expand Down Expand Up @@ -225,13 +230,6 @@ When it successfully completes,
the `bikeshed` module should be globally available for import in Python,
and a `bikeshed` command should now work in your shell.

Finally,
run the following command to update your data files to the latest version:

```bash
bikeshed update
```

#### Installing With Pipenv #### {#install-pipenv}

If you're a user of `pipenv`,
Expand Down Expand Up @@ -661,6 +659,37 @@ so they're specified before the individual commands:
(suitable for parsing as HTML),
for easier parsing of the output by tools.

: `--no-update`
:: By default, Bikeshed checks how old its data files are
every time it runs,
and automatically triggers an update
(as if you ran `bikeshed update`)
if they're more than a few days old.

If this is causing problems
(for example, if something has gone wrong with the update service,
or you are offline
and don't want to wait for the network to timeout),
you can prevent it from doing the check
with `--no-update`.

: `--allow-nonlocal-files`
: `--allow-execute`
:: Bikeshed has the ability to include arbitrary files into your spec,
and in a few cases the ability to execute shell commands or Python
on your behalf
(to allow for some extensions).

By default, these are restricted:
you can only include files from the spec's own folder
or subfolders,
and arbitrary code execution is disallowed.

If you trust the specs you are processing,
and need these abilities, however,
the restrictions can be relaxed
by passing these flags.


`bikeshed spec` {#cli-spec}
---------------------------
Expand Down
67 changes: 47 additions & 20 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1488,9 +1488,9 @@
}
}
</style>
<meta content="Bikeshed version 6904a0588, updated Thu Oct 26 11:27:09 2023 -0700" name="generator">
<meta content="Bikeshed version ea48846c9, updated Fri Nov 10 12:07:00 2023 -0800" name="generator">
<link href="https://speced.github.io/bikeshed/" rel="canonical">
<meta content="6904a0588038005029bac593511264857f3f144d" name="document-revision">
<meta content="ea48846c95d33258f573f1c8f29232b0472354eb" name="document-revision">
<style>/* Boilerplate: style-autolinks */
.css.css, .property.property, .descriptor.descriptor {
color: var(--a-normal-text);
Expand Down Expand Up @@ -2268,7 +2268,7 @@
<div class="head">
<p data-fill-with="logo"></p>
<h1 class="p-name no-ref" id="title">Bikeshed Documentation</h1>
<h2 class="no-num no-toc no-ref heading settled" id="profile-and-date"><span class="content">Living Standard, <time class="dt-updated" datetime="2023-10-26">26 October 2023</time></span></h2>
<h2 class="no-num no-toc no-ref heading settled" id="profile-and-date"><span class="content">Living Standard, <time class="dt-updated" datetime="2023-11-10">10 November 2023</time></span></h2>
<div data-fill-with="spec-metadata">
<dl>
<dt>This version:
Expand All @@ -2283,7 +2283,7 @@ <h2 class="no-num no-toc no-ref heading settled" id="profile-and-date"><span cla
<div data-fill-with="warning"></div>
<p class="copyright" data-fill-with="copyright"><a href="http://creativecommons.org/publicdomain/zero/1.0/" rel="license"><img alt="CC0" height="15" src="https://licensebuttons.net/p/zero/1.0/80x15.png" width="80"></a> To the extent possible under law, the editors have waived all copyright
and related or neighboring rights to this work.
In addition, as of 26 October 2023,
In addition, as of 10 November 2023,
the editors have made this specification available under the <a href="http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0" rel="license">Open Web Foundation Agreement Version 1.0</a>,
which is available at http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0.
Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document. </p>
Expand Down Expand Up @@ -2566,34 +2566,30 @@ <h3 class="heading settled" data-level="1.2" id="install-prereqs"><span class="s
has a few (pretty easy) steps.
(These might already all work for you!)</p>
<h4 class="heading settled" data-level="1.2.1" id="install-py3"><span class="secno">1.2.1. </span><span class="content"><code>python3</code></span><a class="self-link" href="#install-py3"></a></h4>
<p>Bikeshed requires Python 3.7 or later.
<p>Bikeshed requires Python 3.9 or later.
(It’s currently tested up to 3.11.)</p>
<p>To tell what version you have,
run:</p>
<pre class="language-bash highlight">python3 --version
</pre>
<p>If it reports 3.7 or later, you’re fine.</p>
<p>If it reports 3.9 or later, you’re fine.</p>
<p>If it’s earlier, you’ll need to update your local Python version.
There are several ways to do so,
but I recommend <code>pyenv</code> as a safe and easy method.</p>
<p><a href="https://github.com/pyenv/pyenv#installation">https://github.com/pyenv/pyenv#installation</a> gives instructions for installing pyenv on various environments.
It also links to the auto-installer, which can make things even easier.
Windows users have slightly different instructions,
but it links to a windows fork as well.</p>
<p>Note that the final install step currently installs 3.7.8;
that’s fine, go ahead and follow it.</p>
<p>If you know your way around pyenv already,
feel free to do what you’re used to here.
Otherwise, it’s usually easiest to set up 3.7 as your "default" Python:</p>
Otherwise, it’s usually easiest to set up 3.10 as your "default" Python:</p>
<pre class="language-bash highlight">pyenv versions
</pre>
<p>will list what versions exist, and then</p>
<pre class="language-bash highlight">pyenv global <c- m>3</c->.7.0
<pre class="language-bash highlight">pyenv global <c- m>3</c->.10.4
</pre>
<p>will set 3.7.0 as your "global" version, used by default.
<p>will set 3.10.4 as your "global" version, used by default.
(Substitute in whatever the name of the version you saw in <code>versions</code> was.)</p>
<p>(Alternately, use a 3.10 or 3.11 version,
as many Python programs now assume these versions.)</p>
<h4 class="heading settled" data-level="1.2.2" id="install-pipx"><span class="secno">1.2.2. </span><span class="content"><code>pipx</code></span><a class="self-link" href="#install-pipx"></a></h4>
<p>Installing packages globally is usually a bad (and sometimes insecure!) idea.
They should instead be isolated into "virtual environments".
Expand All @@ -2609,23 +2605,30 @@ <h3 class="heading settled" data-level="1.3" id="install-final"><span class="sec
<h4 class="heading settled" data-level="1.3.1" id="install-normal"><span class="secno">1.3.1. </span><span class="content">Installing For Normal Use</span><a class="self-link" href="#install-normal"></a></h4>
<p>Assuming the prereqs (above) are satisfied,
installation is trivial:</p>
<pre class="language-bash highlight">pipx install bikeshed <c- o>&amp;&amp;</c-> bikeshed update
<pre class="language-bash highlight">pipx install bikeshed
</pre>
<p>When this is completed, Bikeshed should be installed,
and the <code>bikeshed</code> command should work in your shell.</p>
<p class="note" role="note"><span class="marker">Note:</span> If this is your first time running <code>pipx</code>,
you might get a message complaining about your PATH variable,
and the <code>bikeshed update</code> command will fail.
and Bikeshed’s attempt to update its data files will fail.
If so, follow <code>pipx</code>’s instructions,
then run <code>bikeshed update</code> again.</p>
<p>After this, invoking Bikeshed is just:</p>
<pre class="language-bash highlight">cd ~/my-spec-folder
bikeshed
</pre>
<p>Remember to update Bikeshed regularly by running:</p>
<pre class="language-bash highlight">pipx upgrade bikeshed <c- o>&amp;&amp;</c-> bikeshed update
<pre class="language-bash highlight">pipx upgrade bikeshed
</pre>
<p>See <a href="#updating-bikeshed">§ 1.4 Updating Bikeshed</a> for more details.</p>
<p>You can also manually refresh Bikeshed’s datafiles by running:</p>
<pre class="language-bash highlight">bikeshed update
</pre>
<p>But this will run automatically
whenever you use Bikeshed
if your data files are more than a few days old,
so it usually shouldn’t be necessary.</p>
<p class="note" role="note"><span class="marker">Note:</span> If you’re on a Mac, <code>bikeshed update</code> might fail with some errors about certificates.
This is a known issue with the version of Python 3.7 shipped with XCode,
which might be the default on your system.
Expand All @@ -2647,10 +2650,6 @@ <h4 class="heading settled" data-level="1.3.2" id="install-dev"><span class="sec
When it successfully completes,
the <code>bikeshed</code> module should be globally available for import in Python,
and a <code>bikeshed</code> command should now work in your shell.</p>
<p>Finally,
run the following command to update your data files to the latest version:</p>
<pre class="language-bash highlight">bikeshed update
</pre>
<h5 class="heading settled" data-level="1.3.2.1" id="install-pipenv"><span class="secno">1.3.2.1. </span><span class="content">Installing With Pipenv</span><a class="self-link" href="#install-pipenv"></a></h5>
<p>If you’re a user of <code>pipenv</code>,
Bikeshed’s folder contains a <code>Pipfile</code> and <code>Pipfile.lock</code> for you.</p>
Expand Down Expand Up @@ -2962,6 +2961,34 @@ <h3 class="heading settled" data-level="3.1" id="cli-options"><span class="secno
"markup" outputs the text in a light markup structure
(suitable for parsing as HTML),
for easier parsing of the output by tools.</p>
<dt data-md><code>--no-update</code>
<dd data-md>
<p>By default, Bikeshed checks how old its data files are
every time it runs,
and automatically triggers an update
(as if you ran <code>bikeshed update</code>)
if they’re more than a few days old.</p>
<p>If this is causing problems
(for example, if something has gone wrong with the update service,
or you are offline
and don’t want to wait for the network to timeout),
you can prevent it from doing the check
with <code>--no-update</code>.</p>
<dt data-md><code>--allow-nonlocal-files</code>
<dt data-md><code>--allow-execute</code>
<dd data-md>
<p>Bikeshed has the ability to include arbitrary files into your spec,
and in a few cases the ability to execute shell commands or Python
on your behalf
(to allow for some extensions).</p>
<p>By default, these are restricted:
you can only include files from the spec’s own folder
or subfolders,
and arbitrary code execution is disallowed.</p>
<p>If you trust the specs you are processing,
and need these abilities, however,
the restrictions can be relaxed
by passing these flags.</p>
</dl>
<h3 class="heading settled" data-level="3.2" id="cli-spec"><span class="secno">3.2. </span><span class="content"><code>bikeshed spec</code></span><a class="self-link" href="#cli-spec"></a></h3>
<p>The <code>spec</code> command is the most common one you’ll use.
Expand Down
4 changes: 2 additions & 2 deletions setup.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,12 @@
packages=find_packages(),
include_package_data=True,
install_requires=install_requires,
python_requires=">=3.7",
python_requires=">=3.9",
classifiers=[
"Development Status :: 5 - Production/Stable",
"License :: Public Domain",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3.7",
"Programming Language :: Python :: 3.9",
"Topic :: Software Development :: Documentation",
],
entry_points={"console_scripts": ["bikeshed = bikeshed:main"]},
Expand Down

0 comments on commit efc762a

Please sign in to comment.