From bb2a5f8d170ab5c9859b5b4c7a02ed3565977478 Mon Sep 17 00:00:00 2001 From: Joe Rickerby Date: Sun, 6 Oct 2019 20:36:21 +0100 Subject: [PATCH] Formatting improvements --- docs/extra.css | 72 ++++++++++++++++++++++++++++++++++++++++++++ docs/extra.js | 5 ++++ docs/options.md | 79 ++++++++++++++++++++++++++++++++++++++++++------- docs/setup.md | 31 +++++++++++++++++-- mkdocs.yml | 13 +++++++- 5 files changed, 187 insertions(+), 13 deletions(-) create mode 100644 docs/extra.css create mode 100644 docs/extra.js diff --git a/docs/extra.css b/docs/extra.css new file mode 100644 index 00000000..42095298 --- /dev/null +++ b/docs/extra.css @@ -0,0 +1,72 @@ + +/* Global styles */ + +p { + margin-bottom: 12px; +} + +code { + font-size: 85%; + background-color: rgba(27,31,35,.05); + border-radius: 3px; + padding: .2em .4em; + color: inherit; + border: none; + margin: 0 1px; +} + +code, pre, tt { + font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace; +} + +.hljs { + padding: 1em; + background-color: #f6f8fa; +} + +/* + Code block filename style + + Use by putting a quote before a code block e.g. + + > filename.txt + + ``` + code here + ``` + + JS adds the relevant classes to make the following selectors work. +*/ +.rst-content .code-block-filename { + margin: 0; + padding: 2px 1em; + background-color: #eff1f3; + font-size: 85%; + font-weight: bold; + + border-top-left-radius: 3px; + border-top-right-radius: 3px; + + border-bottom: 1px solid #e6e8e9; + color: #444; +} + +.rst-content .code-block-filename * { + font-size: inherit; +} +.rst-content .code-block-filename :last-child { + margin-bottom: 0; +} + +.code-block-filename + pre { + margin-top: 0; + border-top-left-radius: 0; + border-top-right-radius: 0; +} + +.code-block-filename + pre code { + padding-top: 0.9em; +} + +/* import font awesome 4 for icons */ +@import url(https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css); diff --git a/docs/extra.js b/docs/extra.js new file mode 100644 index 00000000..d32c3cc0 --- /dev/null +++ b/docs/extra.js @@ -0,0 +1,5 @@ + +$('.rst-content pre') + .prev('blockquote') + .addClass('code-block-filename'); + diff --git a/docs/options.md b/docs/options.md index 12814d01..8c6146fc 100644 --- a/docs/options.md +++ b/docs/options.md @@ -1,24 +1,42 @@ +### Setting options + cibuildwheel is configured using environment variables, that can be set using your CI config. - - - - -
example .travis.yml environment variables
env:
+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:
   global:
     - CIBW_TEST_REQUIRES=nose
     - CIBW_TEST_COMMAND="nosetests {project}/tests"
-
example appveyor.yml environment variables
environment:
+```
+
+> appveyor.yml ([docs](https://www.appveyor.com/docs/build-configuration/#environment-variables))
+```yaml
+environment:
   global:
     CIBW_TEST_REQUIRES: nose
     CIBW_TEST_COMMAND: "nosetests {project}\\tests"
-
example .circleci/config.yml environment variables
jobs:
+```
+
+> .circleci/config.yml ([docs](https://circleci.com/docs/2.0/configuration-reference/#environment))
+```yaml
+jobs:
   job_name:
     environment:
       CIBW_TEST_REQUIRES: nose
-      CIBW_TEST_COMMAND: "nosetests {project}\\tests"
-
+ CIBW_TEST_COMMAND: "nosetests {project}/tests" +``` + +> azure-pipelines.yml ([docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/variables)) +```yaml +variables: + CIBW_TEST_REQUIRES: nose + CIBW_TEST_COMMAND: "nosetests {project}/tests" +``` ## 🚩Build selection @@ -150,7 +168,7 @@ Platform-specific variants also available: ## Command line options -``` +```text usage: cibuildwheel [-h] [--platform {auto,linux,macos,windows}] [--output-dir OUTPUT_DIR] [--print-build-identifiers] [project_dir] @@ -178,3 +196,44 @@ optional arguments: invocation and exit. ``` + + + + diff --git a/docs/setup.md b/docs/setup.md index 2e87c5a8..3ec28623 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -2,7 +2,7 @@ Using Azure pipelines, you can build all three platforms on the same service. Create a `azure-pipelines.yml` file in your repo. -**azure-pipelines.yml** +> azure-pipelines.yml ```yaml jobs: - job: linux @@ -50,6 +50,7 @@ jobs: To build Linux and Mac wheels on Travis CI, create a `.travis.yml` file in your repo. +> .travis.yml ```yaml language: python @@ -74,6 +75,7 @@ Then setup a deployment method by following the [Travis CI deployment docs](http To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file in your repo, +> .circleci/config.yml ```yaml version: 2 @@ -124,6 +126,8 @@ CircleCI will store the built wheels for you - you can access them from the proj To build Windows wheels on AppVeyor, create an `appveyor.yml` file in your repo. +> appveyor.yml + ```yaml build_script: - pip install cibuildwheel==0.12.0 @@ -139,4 +143,27 @@ Commit those files, enable building of your repo on Travis CI and AppVeyor, and All being well, you should get wheels delivered to you in a few minutes. -> ⚠️ Got an error? Check the [checklist](#it-didnt-work) below. +> ⚠️ Got an error? Check the [FAQ](faq.md). + + \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 4c187bd6..2c9caadc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,8 +1,18 @@ site_name: cibuildwheel docs_dir: docs -theme: readthedocs +theme: + name: readthedocs + highlightjs: true + hljs_languages: + - yaml repo_url: https://github.com/joerick/cibuildwheel +extra_css: + - extra.css + +extra_javascript: + - extra.js + nav: - Home: index.md - "Setup guide": setup.md @@ -10,6 +20,7 @@ nav: - deliver-to-pypi.md - faq.md - contributing.md + markdown_extensions: - fenced_code - toc: