Options page rework (incomplete)

docs/options.md

@@ -1,4 +1,58 @@
-### Setting options
+## Options
+
+<div class="toc-grid-marker"></div>
+
+|   |  |   |
+|---|---|---|
+| **Target wheels** |  |  |
+| `CIBW_PLATFORM` | Override the auto-detected target platform |
+| `CIBW_BUILD` | Build only certain Python versions |
+| `CIBW_SKIP` | Skip certain Python versions |
+| **Build parameters** | | |
+| `CIBW_BUILD_VERBOSITY` | Increase or decrease the output of `pip wheel` |
+| **Build environment** | | |
+| `CIBW_ENVIRONMENT` | Set environment variables needed during the build |
+| `CIBW_BEFORE_BUILD` | Execute a shell command preparing each wheel's build |
+| `CIBW_MANYLINUX1_X86_64_IMAGE` | Specify an alternative manylinx1 x86_64 docker image |
+| `CIBW_MANYLINUX1_I686_IMAGE` | Specify an alternative manylinux1 i686 docker image |
+| **Tests** |  | |
+| `CIBW_TEST_COMMAND` | Execute a shell command to test all built wheels |
+| `CIBW_TEST_REQUIRES` | Install Python dependencies before running the tests |
+| `CIBW_TEST_EXTRAS` | Install Python dependencies before running the tests using ``extras_require``|
+
+
+- Target wheels
+    - `CIBW_PLATFORM`
+        - Override the auto-detected target platform
+    - `CIBW_BUILD`
+        - Build only certain Python versions |
+    - `CIBW_SKIP`
+        - Skip certain Python versions |
+- Build parameters
+    - `CIBW_BUILD_VERBOSITY`
+        - Increase or decrease the output of `pip wheel` |
+- Build environment
+    - `CIBW_ENVIRONMENT`
+        - Set environment variables needed during the build |
+    - `CIBW_BEFORE_BUILD`
+        - Execute a shell command preparing each wheel's build |
+    - `CIBW_MANYLINUX1_X86_64_IMAGE`
+        - Specify an alternative manylinx1 x86_64 docker image |
+    - `CIBW_MANYLINUX1_I686_IMAGE`
+        - Specify an alternative manylinux1 i686 docker image |
+- Tests
+    - `CIBW_TEST_COMMAND`
+        - Execute a shell command to test all built wheels |
+    - `CIBW_TEST_REQUIRES`
+        - Install Python dependencies before running the tests |
+    - `CIBW_TEST_EXTRAS`
+        - Install Python dependencies before running the tests using ``extras_require``|
+
+## Options summary
+
+<div class="options-toc"></div>
+
+## Setting options
 
 cibuildwheel is configured using environment variables, that can be set using 
 your CI config.
@@ -38,9 +92,10 @@ variables:
   CIBW_TEST_COMMAND: "nosetests {project}/tests"
 ```
 
-## 🚩Build selection
+## Build selection
 
-### CIBW_PLATFORM - Override the auto-detected target platform {: #platform}
+### CIBW_PLATFORM {: #platform}
+> Override the auto-detected target platform
 
 Options: `auto` `linux` `macos` `windows`
 
@@ -50,7 +105,8 @@ Default: `auto`
 
 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 at `C:\PythonXX[-x64]`.
 
-### CIBW_BUILD, CIBW_SKIP - Choose the Python versions to build {: #build-skip}
+### CIBW_BUILD, CIBW_SKIP {: #build-skip}
+> Choose the Python versions to build
 
 Space-separated list of builds to build and skip. Each build has an identifier like `cp27-manylinux1_x86_64` or `cp34-macosx_10_6_intel` - you can list specific ones to build and `cibuildwheel` will only build those, and/or list ones to skip and `cibuildwheel` won't try to build them.
 
@@ -75,9 +131,10 @@ Examples:
 - Skip Python 3.6 on Linux: `CIBW_SKIP=cp36-manylinux*`
 - Only build on Python 3 and skip 32-bit builds: `CIBW_BUILD=cp3?-*` and `CIBW_SKIP=*-win32 *-manylinux1_i686`
 
-## 🌎 Build environment
+## Build environment
 
-### CIBW_ENVIRONMENT - Set environment variables needed during the build {: #environment}
+### CIBW_ENVIRONMENT {: #environment}
+> Set environment variables needed during the build
 
 A space-separated list of environment variables to set during the build. Bash syntax should be used (even on Windows!).
 
@@ -95,7 +152,8 @@ Platform-specific variants also available:
 
 In addition to the above, `cibuildwheel` always defines the environment variable `CIBUILDWHEEL=1`. This can be useful for [building wheels with optional extensions](https://github.com/joerick/cibuildwheel/wiki/Building-packages-with-optional-C-extensions).
 
-### CIBW_BEFORE_BUILD - Execute a shell command preparing each wheel's build {: #before-build}
+### CIBW_BEFORE_BUILD {: #before-build}
+> Execute a shell command preparing each wheel's build
 
 A shell command to run before building the wheel. This option allows you to run a command in **each** Python environment before the `pip wheel` command. This is useful if you need to set up some dependency so it's available during the build.
 
@@ -110,7 +168,8 @@ Example: `yum install -y libffi-dev && pip install .`
 Platform-specific variants also available:  
  `CIBW_BEFORE_BUILD_MACOS` | `CIBW_BEFORE_BUILD_WINDOWS` | `CIBW_BEFORE_BUILD_LINUX`
 
-### CIBW_MANYLINUX1_X86_64_IMAGE, CIBW_MANYLINUX1_I686_IMAGE - Specify alternative manylinux1 x86_64 docker images {: #manylinux-image}
+### CIBW_MANYLINUX1_X86_64_IMAGE, CIBW_MANYLINUX1_I686_IMAGE {: #manylinux-image}
+> Specify alternative manylinux1 x86_64 docker images 
 
 An alternative docker image to be used for building [`manylinux1`](https://github.com/pypa/manylinux) wheels. `cibuildwheel` will then pull these instead of the official images, [`quay.io/pypa/manylinux1_x86_64`](https://quay.io/pypa/manylinux1_i686) and [`quay.io/pypa/manylinux1_i686`](https://quay.io/pypa/manylinux1_i686).
 
@@ -119,9 +178,10 @@ Beware to specify a valid docker image that can be used the same as the official
 Example: `dockcross/manylinux-x64`  
 Example: `dockcross/manylinux-x86`
 
-## 🔬 Testing
+## Testing
 
-### CIBW_TEST_COMMAND - Execute a shell command to test all built wheels {: #test-command}
+### CIBW_TEST_COMMAND {: #test-command}
+> Execute a shell command to test all built wheels
 
 Shell command to run tests after the build. The wheel will be installed automatically and available for import from the tests. `{project}` can be used as a placeholder for the absolute path to the project's root and will be replaced by `cibuildwheel`.
 
@@ -132,7 +192,8 @@ Example: `nosetests {project}/tests`
 Platform-specific variants also available:
 `CIBW_TEST_COMMAND_MACOS` | `CIBW_TEST_COMMAND_WINDOWS` | `CIBW_TEST_COMMAND_LINUX`
 
-### CIBW_TEST_REQUIRES - Install Python dependencies before running the tests {: #test-requires}
+### CIBW_TEST_REQUIRES {: #test-requires}
+> Install Python dependencies before running the tests
 
 Space-separated list of dependencies required for running the tests.
 
@@ -142,7 +203,8 @@ Example: `nose==1.3.7 moto==0.4.31`
 Platform-specific variants also available:
 `CIBW_TEST_REQUIRES_MACOS` | `CIBW_TEST_REQUIRES_WINDOWS` | `CIBW_TEST_REQUIRES_LINUX`
 
-### CIBW_TEST_EXTRAS - Install your wheel for testing using `extras_require` {: #test-extras}
+### CIBW_TEST_EXTRAS {: #test-extras}
+> Install your wheel for testing using `extras_require`
 
 Comma-separated list of
 [extras_require](https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies)
@@ -157,9 +219,10 @@ Example: `test,qt` (will cause the wheel to be installed with `pip install <whee
 Platform-specific variants also available:
 `CIBW_TEST_EXTRAS_MACOS` | `CIBW_TEST_EXTRAS_WINDOWS` | `CIBW_TEST_EXTRAS_LINUX`
 
-## 💭 Other
+## Other
 
-### CIBW_BUILD_VERBOSITY - Increase/decrease the output of pip wheel
+### CIBW_BUILD_VERBOSITY {: #test-extras}
+> Increase/decrease the output of pip wheel
 
 An number from 1 to 3 to increase the level of verbosity (corresponding to invoking pip with `-v`, `-vv`, and `-vvv`), between -1 and -3 (`-q`, `-qq`, and `-qqq`), or just 0 (default verbosity). These flags are useful while debugging a build when the output of the actual build invoked by `pip wheel` is required.
 
@@ -201,17 +264,40 @@ optional arguments:
   .cibw-option-header {
     margin-top: 5px;
     /* border-bottom: 1px solid rgba(0, 0, 0, 0.05); */
+    font-size: 80%;
+    text-transform: uppercase;
   }
   .cibw-option-header:hover {
     background-color: transparent !important;
   }
   .cibw-option-name {
-    display: block;
-    font-weight: bold;
   }
   .cibw-option-description {
     font-size: 0.9em;
   }
+  .toctree-l3 {
+    border-left: 10px solid transparent;
+  }
+  .rst-content .section .toc-grid-marker + table td {
+    border: none !important;
+    background-color: transparent !important;
+  }
+  .options-toc {
+    display: grid;
+    grid-auto-columns: fit-content(20%) 1fr;
+    grid-gap: 10px;
+    gap: 10px;
+    font-size: 90%;
+    margin-bottom: 24px;
+  }
+  .options-toc .header {
+    grid-column: 1 / 3;
+    font-weight: bold;
+    margin-top: 15px;
+  }
+  .options-toc .header:first-child {
+    margin-top: 0;
+  }
 </style>
 
 <script>
@@ -220,10 +306,78 @@ optional arguments:
     $('.wy-menu-vertical li.current a').each(function(i, el) {
       var $el = $(el);
       $el.html( $el.text().replace(
-        /(^[A-Z0-9, _]+) - (.*)$/,
-        '<div class="cibw-option-name">$1</div><div class="cibw-option-description">$2</div>')
+        /(^([A-Z0-9, _]| and )+)$/,
+        '<div class="cibw-option-name">$1</div>')
       );
-    })
+    });
+
+    // var optionList = []
+
+    // $('.rst-content .section').children().each(function (i, el) {
+    //   if (el.tagName == 'H2') {
+    //     optionList.push({
+    //       type: 'header',
+    //       name: el.textContent,
+    //     })
+    //   }
+    //   if (el.tagName == 'H3') {
+    //     optionList.push({
+    //       type: 'option', 
+    //       name: el.textContent, 
+    //       description: $(el).next('blockquote').text(),
+    //     })
+    //   }
+    //   console.log(optionList);
+
+    //   var gridEl = $('.options-toc');
+    //   optionsList.forEach(function (item) {
+    //     if (item.type == 'header')
+    //   })
+    //   gridEl.append
+    // });
+
+    var options = {}
+    var headers = []
+
+    $('.rst-content h3')
+      .filter(function (i, el) {
+        return !!$(el).text().match(/(^([A-Z0-9, _]| and )+)¶$/);
+      })
+      .each(function (i, el) {
+        var optionName = $(el).text().replace('¶', '');
+        var description = $(el).next('blockquote').text()
+        var header = $(el).prevAll('h2').first().text().replace('¶', '')
+        var id = el.id;
+
+        if (options[header] === undefined) {
+          options[header] = [];
+          headers.push(header);
+        }
+        console.log(optionName, description, header);
+
+        options[header].push({name: optionName, description, id});
+      });
+
+    var tocTable = $('.options-toc');
+
+    for (var i = 0; i < headers.length; i += 1) {
+      var header = headers[i];
+      var headerOptions = options[header];
+
+      $('<div class="header">').text(header).appendTo(tocTable);
+
+      for (var j = 0; j < headerOptions.length; j += 1) {
+        var option = headerOptions[j];
+
+        $('<a class="name">')
+          .text(option.name)
+          .attr('href', '#'+option.id)
+          .appendTo(tocTable);
+        $('<div class="description">').text(option.description).appendTo(tocTable);
+      }
+    }
+
+    console.log(options);
     
     // add styling classes to the emoji headers
     $('.wy-menu-vertical li.current a').each(function(i, el) {
@@ -234,6 +388,6 @@ optional arguments:
       if (text.match(emojiStartRegex)) {
         $el.addClass('cibw-option-header')
       }
-    })
-  })
+    });
+  });
 </script>