docs: support tabs (#576)
* docs: support tabs * Get superfences working * Use an 'admonition' as a tab, add some styling * docs: reorder tabs and modernize * docs: tabbed options settings * docs: reorder to match order in other places * docs: correct the example * Apply suggestions from code review (lazy edits in GH :) ) * Update mkdocs-include-markdown-plugin and remove unneeded include option Co-authored-by: Joe Rickerby <joerick@mac.com>
This commit is contained in:
Henry Schreiner
co-authored by
Joe Rickerby
Joe Rickerby
parent
bb14c67835
commit
58c5e56e9f
@@ -89,3 +89,59 @@ h1, h2, h3, h4, h5, h6 {
|
||||
|
||||
/* import font awesome 4 for icons */
|
||||
@import url(https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css);
|
||||
|
||||
|
||||
/* Tabs */
|
||||
|
||||
/* Style the tab */
|
||||
.tabs {
|
||||
margin-bottom: 1em;
|
||||
-webkit-font-smoothing: antialiased;
|
||||
}
|
||||
|
||||
.tabs-header {
|
||||
background-color: white;
|
||||
display: flex;
|
||||
justify-content: flex-start;
|
||||
border-bottom: 2px solid #ccc;
|
||||
}
|
||||
|
||||
/* Style the buttons that are used to open the tab content */
|
||||
.tabs-header button {
|
||||
background-color: transparent;
|
||||
border: none;
|
||||
outline: none;
|
||||
cursor: pointer;
|
||||
color: inherit;
|
||||
font: inherit;
|
||||
font-size: 0.9em;
|
||||
font-weight: 600;
|
||||
padding: 8px 16px;
|
||||
border-bottom: 2px solid transparent;
|
||||
|
||||
/* put the border on top of the parent border */
|
||||
margin-bottom: -2px;
|
||||
}
|
||||
|
||||
.tabs-header button:focus-visible {
|
||||
/* preserve an outline for accesibility purposes */
|
||||
outline: 1px solid currentColor;
|
||||
}
|
||||
|
||||
/* Change background color of buttons on hover */
|
||||
.tabs-header button:hover {
|
||||
background-color: rgba(0, 0, 0, 0.02);
|
||||
}
|
||||
|
||||
/* Create an active/current tablink class */
|
||||
.tabs-header button.active {
|
||||
color: #4086bd;
|
||||
border-bottom-color: currentColor;
|
||||
}
|
||||
|
||||
/* Style the tab content */
|
||||
.tabs-content {
|
||||
background-color: #f1f6fa;
|
||||
padding: 1px 1em;
|
||||
padding-top: 0.8em;
|
||||
}
|
||||
|
||||
+46
-1
@@ -1,4 +1,49 @@
|
||||
|
||||
// add classes for code-block-filename styling
|
||||
$('.rst-content pre')
|
||||
.prev('blockquote')
|
||||
.addClass('code-block-filename');
|
||||
|
||||
var tabConversionIterations = 0
|
||||
|
||||
// convert tab admonition to tabs
|
||||
while (true) {
|
||||
const firstTab = $('.rst-content .admonition.tab').first()
|
||||
if (firstTab.length == 0) break;
|
||||
|
||||
const otherTabs = firstTab.nextUntil(':not(.admonition.tab)');
|
||||
const allTabs = $($.merge($.merge([], firstTab), otherTabs));
|
||||
|
||||
const tabContainer = $('<div>').addClass('tabs');
|
||||
const headerContainer = $('<div>').addClass('tabs-header');
|
||||
const contentContainer = $('<div>').addClass('tabs-content');
|
||||
|
||||
tabContainer.insertBefore(firstTab);
|
||||
tabContainer.append(headerContainer, contentContainer)
|
||||
|
||||
const selectTab = function (index) {
|
||||
headerContainer.children().removeClass('active')
|
||||
headerContainer.children().eq(index).addClass('active')
|
||||
contentContainer.children().hide()
|
||||
contentContainer.children().eq(index).show()
|
||||
}
|
||||
|
||||
allTabs.each(function (tabI, el) {
|
||||
const $el = $(el)
|
||||
const titleElement = $el.children('.admonition-title')
|
||||
const title = titleElement.text()
|
||||
const button = $('<button>').text(title)
|
||||
button.click(function () {
|
||||
selectTab(tabI)
|
||||
})
|
||||
headerContainer.append(button)
|
||||
|
||||
titleElement.remove()
|
||||
$el.removeClass('admonition')
|
||||
contentContainer.append($el)
|
||||
})
|
||||
|
||||
selectTab(0)
|
||||
|
||||
// this will catch infinite loops which can occur when editing the above
|
||||
if (tabConversionIterations++ > 1000) throw 'too many iterations'
|
||||
}
|
||||
|
||||
@@ -105,6 +105,7 @@ Actions. Once QEMU is set up and registered, you just need to set the
|
||||
Linux), and the other architectures are emulated automatically.
|
||||
|
||||
> .github/workflows/build.yml
|
||||
|
||||
```yaml
|
||||
{% include "../examples/github-with-qemu.yml" %}
|
||||
```
|
||||
@@ -130,6 +131,7 @@ Hopefully, this is a temporary situation. Once we have widely available Apple Si
|
||||
Here's an example GitHub Actions workflow with a job that builds for Apple Silicon:
|
||||
|
||||
> .github/workflows/build_macos.yml
|
||||
|
||||
```yml
|
||||
{% include "../examples/github-apple-silicon.yml" %}
|
||||
```
|
||||
|
||||
+50
-22
@@ -10,44 +10,72 @@ your CI config.
|
||||
For example, to configure cibuildwheel to run tests, add the following YAML to
|
||||
your CI config file:
|
||||
|
||||
> .travis.yml ([docs](https://docs.travis-ci.com/user/environment-variables/))
|
||||
```yaml
|
||||
env:
|
||||
|
||||
!!! tab "GitHub Actions"
|
||||
|
||||
> .github/workflows/*.yml ([docs](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables)) (can be global, in job, or in step)
|
||||
|
||||
```yaml
|
||||
env:
|
||||
CIBW_TEST_REQUIRES: pytest
|
||||
CIBW_TEST_COMMAND: "pytest {project}/tests"
|
||||
```
|
||||
|
||||
!!! tab "Azure Pipelines"
|
||||
|
||||
> azure-pipelines.yml ([docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/variables))
|
||||
|
||||
```yaml
|
||||
variables:
|
||||
CIBW_TEST_REQUIRES: pytest
|
||||
CIBW_TEST_COMMAND: "pytest {project}/tests"
|
||||
```
|
||||
|
||||
!!! tab "Travis CI"
|
||||
|
||||
> .travis.yml ([docs](https://docs.travis-ci.com/user/environment-variables/))
|
||||
|
||||
```yaml
|
||||
env:
|
||||
global:
|
||||
- CIBW_TEST_REQUIRES=pytest
|
||||
- CIBW_TEST_COMMAND="pytest {project}/tests"
|
||||
```
|
||||
```
|
||||
|
||||
> appveyor.yml ([docs](https://www.appveyor.com/docs/build-configuration/#environment-variables))
|
||||
```yaml
|
||||
environment:
|
||||
!!! tab "AppVeyor"
|
||||
|
||||
> appveyor.yml ([docs](https://www.appveyor.com/docs/build-configuration/#environment-variables))
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
global:
|
||||
CIBW_TEST_REQUIRES: pytest
|
||||
CIBW_TEST_COMMAND: "pytest {project}\\tests"
|
||||
```
|
||||
```
|
||||
|
||||
> .circleci/config.yml ([docs](https://circleci.com/docs/2.0/configuration-reference/#environment))
|
||||
```yaml
|
||||
jobs:
|
||||
!!! tab "CircleCI"
|
||||
|
||||
> .circleci/config.yml ([docs](https://circleci.com/docs/2.0/configuration-reference/#environment))
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
job_name:
|
||||
environment:
|
||||
CIBW_TEST_REQUIRES: pytest
|
||||
CIBW_TEST_COMMAND: "pytest {project}/tests"
|
||||
```
|
||||
```
|
||||
|
||||
> azure-pipelines.yml ([docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/variables))
|
||||
```yaml
|
||||
variables:
|
||||
!!! tab "Gitlab CI"
|
||||
|
||||
> .gitlab-ci.yml ([docs](https://docs.gitlab.com/ee/ci/variables/README.html#create-a-custom-variable-in-gitlab-ciyml))
|
||||
|
||||
```yaml
|
||||
linux:
|
||||
variables:
|
||||
CIBW_TEST_REQUIRES: pytest
|
||||
CIBW_TEST_COMMAND: "pytest {project}/tests"
|
||||
```
|
||||
```
|
||||
|
||||
> .github/workflows/*.yml ([docs](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables)) (can be global, in job, or in step)
|
||||
```yaml
|
||||
env:
|
||||
CIBW_TEST_REQUIRES: pytest
|
||||
CIBW_TEST_COMMAND: "pytest {project}/tests"
|
||||
```
|
||||
|
||||
|
||||
## Build selection
|
||||
|
||||
+127
-35
@@ -4,12 +4,101 @@ title: 'Setup'
|
||||
|
||||
# GitHub Actions [linux/mac/windows] {: #github-actions}
|
||||
|
||||
To build Linux, Mac, and Windows wheels using GitHub Actions, create a `.github/workflows/build.yml` file in your repo.
|
||||
To build Linux, Mac, and Windows wheels using GitHub Actions, create a `.github/workflows/build_wheels.yml` file in your repo.
|
||||
|
||||
!!! tab "Action"
|
||||
For GitHub Actions, `cibuildwheel` provides an action you can use. This is
|
||||
concise and enables easier auto updating via GitHub's Dependabot; see
|
||||
[Automatic updates](faq.md#automatic-updates).
|
||||
|
||||
> .github/workflows/build_wheels.yml
|
||||
|
||||
```yaml
|
||||
{% include "../examples/github-minimal.yml" %}
|
||||
```
|
||||
|
||||
|
||||
You can use `env:` with the action just like you would with `run:`; you can
|
||||
also use `with:` to set the command line options: `package-dir: .` and
|
||||
`output-dir: wheelhouse` (those values are the defaults).
|
||||
|
||||
!!! tab "pipx"
|
||||
The GitHub Actions runners have pipx installed, so you can easily build in
|
||||
just one line. This is internally how the action works; the main benefit of
|
||||
the action form is easy updates via GitHub's Dependabot.
|
||||
|
||||
> .github/workflows/build_wheels.yml
|
||||
|
||||
```yaml
|
||||
name: Build
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
build_wheels:
|
||||
name: Build wheels on ${{ matrix.os }}
|
||||
runs-on: ${{ matrix.os }}
|
||||
strategy:
|
||||
matrix:
|
||||
os: [ubuntu-20.04, windows-2019, macos-10.15]
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
|
||||
- name: Install Visual C++ for Python 2.7
|
||||
if: runner.os == 'Windows'
|
||||
run: choco install vcpython27 -f -y
|
||||
|
||||
- name: Build wheels
|
||||
run: pix run cibuildwheel==1.8.0
|
||||
|
||||
- uses: actions/upload-artifact@v2
|
||||
with:
|
||||
path: ./wheelhouse/*.whl
|
||||
```
|
||||
|
||||
!!! tab "Generic"
|
||||
This is the most generic form using setup-python and pip; it looks the most
|
||||
like the other CI examples. If you want to avoid having setup that takes
|
||||
advantage of GitHub Actions features or pipx being preinstalled, this might
|
||||
appeal to you.
|
||||
|
||||
> .github/workflows/build_wheels.yml
|
||||
|
||||
```yaml
|
||||
name: Build
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
build_wheels:
|
||||
name: Build wheels on ${{ matrix.os }}
|
||||
runs-on: ${{ matrix.os }}
|
||||
strategy:
|
||||
matrix:
|
||||
os: [ubuntu-20.04, windows-2019, macos-10.15]
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
|
||||
# Used to host cibuildwheel
|
||||
- uses: actions/setup-python@v2
|
||||
|
||||
- name: Install cibuildwheel
|
||||
run: python -m pip install cibuildwheel==1.9.0
|
||||
|
||||
- name: Install Visual C++ for Python 2.7
|
||||
if: runner.os == 'Windows'
|
||||
run: choco install vcpython27 -f -y
|
||||
|
||||
- name: Build wheels
|
||||
run: python -m cibuildwheel --output-dir wheelhouse
|
||||
|
||||
- uses: actions/upload-artifact@v2
|
||||
with:
|
||||
path: ./wheelhouse/*.whl
|
||||
```
|
||||
|
||||
> build.yml
|
||||
```yaml
|
||||
{% include "../examples/github-minimal.yml" %}
|
||||
```
|
||||
|
||||
Commit this file, and push to GitHub - either to your default branch, or to a PR branch. The build should start automatically.
|
||||
|
||||
@@ -17,13 +106,13 @@ For more info on this file, check out the [docs](https://help.github.com/en/acti
|
||||
|
||||
[`examples/github-deploy.yml`](https://github.com/joerick/cibuildwheel/blob/master/examples/github-deploy.yml) extends this minimal example with a demonstration of how to automatically upload the built wheels to PyPI.
|
||||
|
||||
You can also use cibuildwheel directly as an action with `uses: joerick/cibuildwheel@v1.9.0`; this combines the download and run steps into a single action, and command line arguments are available via `with:`. This makes it easy to manage cibuildwheel updates via normal actions update mechanisms like dependabot, see [Automatic updates](faq.md#automatic-updates).
|
||||
|
||||
# Azure Pipelines [linux/mac/windows] {: #azure-pipelines}
|
||||
|
||||
To build Linux, Mac, and Windows wheels on Azure Pipelines, create a `azure-pipelines.yml` file in your repo.
|
||||
|
||||
> azure-pipelines.yml
|
||||
|
||||
```yaml
|
||||
{% include "../examples/azure-pipelines-minimal.yml" %}
|
||||
```
|
||||
@@ -40,6 +129,7 @@ Wheels will be stored for you and available through the Pipelines interface. For
|
||||
To build Linux, Mac, and Windows wheels on Travis CI, create a `.travis.yml` file in your repo.
|
||||
|
||||
> .travis.yml
|
||||
|
||||
```yaml
|
||||
{% include "../examples/travis-ci-minimal.yml" %}
|
||||
```
|
||||
@@ -52,35 +142,6 @@ Then setup a deployment method by following the [Travis CI deployment docs](http
|
||||
|
||||
[`examples/travis-ci-deploy.yml`](https://github.com/joerick/cibuildwheel/blob/master/examples/travis-ci-deploy.yml) extends this minimal example with a demonstration of how to automatically upload the built wheels to PyPI.
|
||||
|
||||
# CircleCI [linux/mac] {: #circleci}
|
||||
|
||||
To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file in your repo,
|
||||
|
||||
> .circleci/config.yml
|
||||
```yaml
|
||||
{% include "../examples/circleci-minimal.yml" %}
|
||||
```
|
||||
|
||||
Commit this file, enable building of your repo on CircleCI, and push.
|
||||
|
||||
!!! note
|
||||
CircleCI doesn't enable free macOS containers for open source by default, but you can ask for access. See [here](https://circleci.com/docs/2.0/oss/#overview) for more information.
|
||||
|
||||
CircleCI will store the built wheels for you - you can access them from the project console. Check out the CircleCI [docs](https://circleci.com/docs/2.0/configuration-reference/#section=configuration) for more info on this config file.
|
||||
|
||||
# Gitlab CI [linux] {: #gitlab-ci}
|
||||
|
||||
To build Linux wheels on Gitlab CI, create a `.gitlab-ci.yml` file in your repo,
|
||||
|
||||
> .gitlab-ci.yml
|
||||
```yaml
|
||||
{% include "../examples/gitlab-minimal.yml" %}
|
||||
```
|
||||
|
||||
Commit this file, and push to Gitlab. The pipeline should start automatically.
|
||||
|
||||
Gitlab will store the built wheels for you - you can access them from the Pipelines view. Check out the Gitlab [docs](https://docs.gitlab.com/ee/ci/yaml/) for more info on this config file.
|
||||
|
||||
# AppVeyor [linux/mac/windows] {: #appveyor}
|
||||
|
||||
To build Linux, Mac, and Windows wheels on AppVeyor, create an `appveyor.yml` file in your repo.
|
||||
@@ -97,6 +158,37 @@ AppVeyor will store the built wheels for you - you can access them from the proj
|
||||
|
||||
For more info on this config file, check out the [docs](https://www.appveyor.com/docs/).
|
||||
|
||||
# CircleCI [linux/mac] {: #circleci}
|
||||
|
||||
To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file in your repo,
|
||||
|
||||
> .circleci/config.yml
|
||||
|
||||
```yaml
|
||||
{% include "../examples/circleci-minimal.yml" %}
|
||||
```
|
||||
|
||||
Commit this file, enable building of your repo on CircleCI, and push.
|
||||
|
||||
!!! note
|
||||
CircleCI doesn't enable free macOS containers for open source by default, but you can ask for access. See [here](https://circleci.com/docs/2.0/oss/#overview) for more information.
|
||||
|
||||
CircleCI will store the built wheels for you - you can access them from the project console. Check out the CircleCI [docs](https://circleci.com/docs/2.0/configuration-reference/#section=configuration) for more info on this config file.
|
||||
|
||||
# Gitlab CI [linux] {: #gitlab-ci}
|
||||
|
||||
To build Linux wheels on Gitlab CI, create a `.gitlab-ci.yml` file in your repo,
|
||||
|
||||
> .gitlab-ci.yml
|
||||
|
||||
```yaml
|
||||
{% include "../examples/gitlab-minimal.yml" %}
|
||||
```
|
||||
|
||||
Commit this file, and push to Gitlab. The pipeline should start automatically.
|
||||
|
||||
Gitlab will store the built wheels for you - you can access them from the Pipelines view. Check out the Gitlab [docs](https://docs.gitlab.com/ee/ci/yaml/) for more info on this config file.
|
||||
|
||||
> ⚠️ Got an error? Check the [FAQ](faq.md).
|
||||
|
||||
<script>
|
||||
|
||||
+5
-1
@@ -25,13 +25,17 @@ nav:
|
||||
- changelog.md
|
||||
|
||||
markdown_extensions:
|
||||
- fenced_code
|
||||
- md_in_html
|
||||
- toc:
|
||||
permalink: True
|
||||
- attr_list
|
||||
- admonition
|
||||
- pymdownx.magiclink:
|
||||
repo_url_shortener: True
|
||||
- pymdownx.highlight:
|
||||
# use highlightjs - it's built-in to the theme
|
||||
use_pygments: False
|
||||
- pymdownx.superfences
|
||||
|
||||
plugins:
|
||||
- include-markdown
|
||||
|
||||
Reference in New Issue
Block a user