Add a mkdocs extension to generate the --help output (#720)

* Add a mkdocs extension to generate the --help output

* Add the correct setuptools syntax for relative requirements

* docs: use macro plugin instead

* docs: remove indirection in docs

Co-authored-by: Henry Schreiner <henryschreineriii@gmail.com>

.pre-commit-config.yaml

@@ -45,7 +45,7 @@ repos:
   rev: v0.902
   hooks:
   - id: mypy
-    exclude: ^(bin/|cibuildwheel/resources/).*py$
+    exclude: ^(bin|cibuildwheel/resources|docs)/.*py$
     args: ["--python-version=3.6", "--scripts-are-modules"]
     additional_dependencies:
       - packaging
@@ -54,7 +54,7 @@ repos:
       - types-toml
   - id: mypy
     name: mypy 3.7+ on bin/
-    files: ^bin/.*py$
+    files: ^(bin|docs)/.*py$
     args: ["--python-version=3.7", "--scripts-are-modules"]
     additional_dependencies:
       - packaging

docs/main.py

@@ -0,0 +1,13 @@
+import subprocess
+from typing import Any
+
+# Requires Python 3.7+
+
+
+def define_env(env: Any) -> None:
+    "Hook function for mkdocs-macros"
+
+    @env.macro
+    def subprocess_run(*args: str) -> str:
+        "Run a subprocess and return the stdout"
+        return subprocess.run(args, check=True, capture_output=True, text=True).stdout

docs/options.md

@@ -1114,55 +1114,7 @@ Platform-specific environment variables are also available:<br/>
 ## Command line options {: #command-line}
 
 ```text
-usage: cibuildwheel [-h] [--platform {auto,linux,macos,windows}]
-                    [--archs ARCHS] [--output-dir OUTPUT_DIR]
-                    [--config-file CONFIG_FILE] [--print-build-identifiers]
-                    [--allow-empty] [--prerelease-pythons]
-                    [package_dir]
-
-Build wheels for all the platforms.
-
-positional arguments:
-  package_dir           Path to the package that you want wheels for. Must be
-                        a subdirectory of the working directory. When set, the
-                        working directory is still considered the 'project'
-                        and is copied into the Docker container on Linux.
-                        Default: the working directory.
-
-optional arguments:
-  -h, --help            show this help message and exit
-  --platform {auto,linux,macos,windows}
-                        Platform to build for. For "linux" you need docker
-                        running, on Mac or Linux. For "macos", you need a Mac
-                        machine, and note that this script is going to
-                        automatically install MacPython on your system, so
-                        don't run on your development machine. For "windows",
-                        you need to run in Windows, and it will build and test
-                        for all versions of Python. Default: auto.
-  --archs ARCHS         Comma-separated list of CPU architectures to build
-                        for. When set to 'auto', builds the architectures
-                        natively supported on this machine. Set this option to
-                        build an architecture via emulation, for example,
-                        using binfmt_misc and QEMU. Default: auto. Choices:
-                        auto, auto64, auto32, native, all, x86_64, i686,
-                        aarch64, ppc64le, s390x, universal2, arm64, x86, AMD64
-  --output-dir OUTPUT_DIR
-                        Destination folder for the wheels.
-  --config-file CONFIG_FILE
-                        TOML config file for cibuildwheel; usually
-                        pyproject.toml, but can be overridden with this
-                        option. Use {package} for the package directory.
-  --print-build-identifiers
-                        Print the build identifiers matched by the current
-                        invocation and exit.
-  --allow-empty         Do not report an error code if the build does not
-                        match any wheels.
-  --prerelease-pythons  Enable pre-release Python versions if available.
-
-Most options are supplied via environment variables or in --config-file
-(pyproject.toml usually). See https://github.com/pypa/cibuildwheel#options for
-info.
-```
+« subprocess_run("cibuildwheel", "--help") »
 ```
 
 <style>

mkdocs.yml

@@ -41,3 +41,7 @@ markdown_extensions:
 plugins:
   - include-markdown
   - search
+  - macros:
+      module_name: docs/main
+      j2_variable_start_string: «
+      j2_variable_end_string: »

setup.py

@@ -5,6 +5,7 @@ extras = {
         "mkdocs-include-markdown-plugin==2.8.0",
         "mkdocs==1.0.4",
         "pymdown-extensions",
+        "mkdocs-macros-plugin",
     ],
     "test": [
         "jinja2",