Skip to content

Commit 1d34f85

Browse files
joerickhenryiii
joerick
and
henryiii
authored
General docs improvements for v3.0 (#2280)
* Split the docs into sections * Split the options page into two pages - so the reference is more clean * Reorder/Tidy up this 'deliver' page to make auto-deploy more obvious * Fix up some links * Merge the platform docs into a single page to clean up the navbar. * Split the setup page to make a page dedicated to CI setup * Move general platform-specific information into the platforms page * Tidy up the platforms page * Remove some redundancy in the cpp/platforms docs * Clarify this section * Move another FAQ entry to the platforms page * Remove some out-of-date entries from the FAQ * A few corrections to the options page * Fix some broken links * Improve the Docker references * Update bump version filename * Improve options TOC information density * whitespace Co-authored-by: Henry Schreiner <[email protected]> * Convert the normal test invocation to `pytest ./tests`, not placeholder --------- Co-authored-by: Henry Schreiner <[email protected]>
1 parent 74a7d8a commit 1d34f85

21 files changed

+817
-855
lines changed

‎bin/bump_version.py

+1
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
("docs/faq.md", "cibuildwheel=={}"),
2424
("docs/faq.md", "cibuildwheel@v{}"),
2525
("docs/setup.md", "cibuildwheel=={}"),
26+
("docs/ci-services.md", "cibuildwheel=={}"),
2627
("examples/*", "cibuildwheel=={}"),
2728
("examples/*", "cibuildwheel@v{}"),
2829
]

‎docs/ci-services.md

+185
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
---
2+
title: Configuring a CI service
3+
---
4+
5+
## Configuring a CI service
6+
7+
cibuildwheel works on many popular CI services. Others may work, but it will depend on the software installed on the CI machine/image. See the [platforms page](platforms.md) for details.
8+
9+
### GitHub Actions [linux/mac/windows] {: #github-actions}
10+
11+
To build Linux, macOS, and Windows wheels using GitHub Actions, create a `.github/workflows/build_wheels.yml` file in your repo.
12+
13+
!!! tab "Action"
14+
For GitHub Actions, `cibuildwheel` provides an action you can use. This is
15+
concise and enables easier auto updating via GitHub's Dependabot; see
16+
[Automatic updates](faq.md#automatic-updates).
17+
18+
> .github/workflows/build_wheels.yml
19+
20+
```yaml
21+
{% include "../examples/github-minimal.yml" %}
22+
```
23+
24+
Use `env:` to pass [build options](options.md) and `with:` to set
25+
`package-dir: .`, `output-dir: wheelhouse` and `config-file: ''`
26+
locations (those values are the defaults).
27+
28+
!!! tab "pipx"
29+
The GitHub Actions runners have pipx installed, so you can easily build in
30+
just one line. This is internally how the action works; the main benefit of
31+
the action form is easy updates via GitHub's Dependabot.
32+
33+
> .github/workflows/build_wheels.yml
34+
35+
```yaml
36+
{% include "../examples/github-pipx.yml" %}
37+
```
38+
39+
!!! tab "Generic"
40+
This is the most generic form using setup-python and pip; it looks the most
41+
like the other CI examples. If you want to avoid having setup that takes
42+
advantage of GitHub Actions features or pipx being preinstalled, this might
43+
appeal to you.
44+
45+
> .github/workflows/build_wheels.yml
46+
{%
47+
include-markdown "../README.md"
48+
start="<!--generic-github-start-->"
49+
end="<!--generic-github-end-->"
50+
%}
51+
52+
Commit this file, and push to GitHub - either to your default branch, or to a PR branch. The build should start automatically.
53+
54+
For more info on this file, check out the [docs](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions).
55+
56+
[`examples/github-deploy.yml`](https://github.com/pypa/cibuildwheel/blob/main/examples/github-deploy.yml) extends this minimal example to include iOS and Pyodide builds, and a demonstration of how to automatically upload the built wheels to PyPI.
57+
58+
59+
### Azure Pipelines [linux/mac/windows] {: #azure-pipelines}
60+
61+
To build Linux, Mac, and Windows wheels on Azure Pipelines, create a `azure-pipelines.yml` file in your repo.
62+
63+
> azure-pipelines.yml
64+
65+
```yaml
66+
{% include "../examples/azure-pipelines-minimal.yml" %}
67+
```
68+
69+
Commit this file, enable building of your repo on Azure Pipelines, and push.
70+
71+
Wheels will be stored for you and available through the Pipelines interface. For more info on this file, check out the [docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema).
72+
73+
### Travis CI [linux/windows] {: #travis-ci}
74+
75+
To build Linux and Windows wheels on Travis CI, create a `.travis.yml` file in your repo.
76+
77+
> .travis.yml
78+
79+
```yaml
80+
{% include "../examples/travis-ci-minimal.yml" %}
81+
```
82+
83+
Commit this file, enable building of your repo on Travis CI, and push.
84+
85+
Then setup a deployment method by following the [Travis CI deployment docs](https://docs.travis-ci.com/user/deployment/), or see [Delivering to PyPI](deliver-to-pypi.md). For more info on `.travis.yml`, check out the [docs](https://docs.travis-ci.com/).
86+
87+
[`examples/travis-ci-deploy.yml`](https://github.com/pypa/cibuildwheel/blob/main/examples/travis-ci-deploy.yml) extends this minimal example with a demonstration of how to automatically upload the built wheels to PyPI.
88+
89+
### AppVeyor [linux/mac/windows] {: #appveyor}
90+
91+
To build Linux, Mac, and Windows wheels on AppVeyor, create an `appveyor.yml` file in your repo.
92+
93+
> appveyor.yml
94+
95+
```yaml
96+
{% include "../examples/appveyor-minimal.yml" %}
97+
```
98+
99+
Commit this file, enable building of your repo on AppVeyor, and push.
100+
101+
AppVeyor will store the built wheels for you - you can access them from the project console. Alternatively, you may want to store them in the same place as the Travis CI build. See [AppVeyor deployment docs](https://www.appveyor.com/docs/deployment/) for more info, or see [Delivering to PyPI](deliver-to-pypi.md) below.
102+
103+
For more info on this config file, check out the [docs](https://www.appveyor.com/docs/).
104+
105+
### CircleCI [linux/mac] {: #circleci}
106+
107+
To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file in your repo,
108+
109+
> .circleci/config.yml
110+
111+
```yaml
112+
{% include "../examples/circleci-minimal.yml" %}
113+
```
114+
115+
Commit this file, enable building of your repo on CircleCI, and push.
116+
117+
!!! note
118+
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.
119+
120+
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.
121+
122+
### Gitlab CI [linux] {: #gitlab-ci}
123+
124+
To build Linux wheels on Gitlab CI, create a `.gitlab-ci.yml` file in your repo,
125+
126+
> .gitlab-ci.yml
127+
128+
```yaml
129+
{% include "../examples/gitlab-minimal.yml" %}
130+
```
131+
132+
Commit this file, and push to Gitlab. The pipeline should start automatically.
133+
134+
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.
135+
136+
### Cirrus CI [linux/mac/windows] {: #cirrus-ci}
137+
138+
To build Linux, Mac, and Windows wheels on Cirrus CI, create a `.cirrus.yml` file in your repo,
139+
140+
> .cirrus.yml
141+
142+
```yaml
143+
{% include "../examples/cirrus-ci-minimal.yml" %}
144+
```
145+
146+
Commit this file, enable building of your repo on Cirrus CI, and push.
147+
148+
Cirrus CI will store the built wheels for you - you can access them from the individual task view. Check out the Cirrus CI [docs](https://cirrus-ci.org/guide/writing-tasks/) for more info on this config file.
149+
150+
> ⚠️ Got an error? Check the [FAQ](faq.md).
151+
152+
## Next steps
153+
154+
Once you've got the wheel building successfully, you might want to set up [testing](options.md#test-command) or [automatic releases to PyPI](deliver-to-pypi.md#automatic-method).
155+
156+
<script>
157+
document.addEventListener('DOMContentLoaded', function() {
158+
$('.toctree-l2>a, .rst-content h3').each(function(i, el) {
159+
var text = $(el).text()
160+
var match = text.match(/(.*) \[([a-z/]+)\]/);
161+
162+
if (match) {
163+
var iconHTML = $.map(match[2].split('/'), function(ident) {
164+
switch (ident) {
165+
case 'linux':
166+
return '<i class="fa fa-linux" aria-hidden="true"></i>'
167+
case 'windows':
168+
return '<i class="fa fa-windows" aria-hidden="true"></i>'
169+
case 'mac':
170+
return '<i class="fa fa-apple" aria-hidden="true"></i>'
171+
}
172+
}).join(' ');
173+
174+
$(el).append(
175+
$('<div>')
176+
.append(iconHTML)
177+
.css({float: 'right'})
178+
)
179+
$(el).contents()
180+
.filter(function(){ return this.nodeType == 3; }).first()
181+
.replaceWith(match[1]);
182+
}
183+
});
184+
});
185+
</script>

0 commit comments

Comments
 (0)