Merge pull request #1235 from pypa/docs-update

Update docs toolchain

docs/changelog.md

@@ -2,6 +2,8 @@
 title: Changelog
 ---
 
+# Changelog
+
 ### v2.9.0
 
 _11 August 2022_

docs/contributing.md

@@ -2,6 +2,8 @@
 title: Contributing
 ---
 
+# Contributing
+
 Wheel-building can be pretty complex. We expect users to find edge-cases - please help the rest of the community out by documenting these, adding features to support them, and reporting bugs.
 
 If you have an idea for a modification or feature, it's probably best to raise an issue first and discuss it with the maintainer team. Once we have rough consensus on a design, begin work in a PR.

docs/cpp_standards.md

@@ -2,6 +2,8 @@
 title: Modern C++ standards
 ---
 
+# Modern C++ standards
+
 Building Python wheels with modern C++ standards (C++11 and later) requires a few tricks.
 
 

docs/deliver-to-pypi.md

@@ -2,6 +2,8 @@
 title: Delivering to PyPI
 ---
 
+# Delivering to PyPI
+
 After you've built your wheels, you'll probably want to deliver them to PyPI.
 
 ## Manual method

docs/extra.css

@@ -4,6 +4,7 @@
 body {
     overflow-wrap: break-word;
     overflow-x: hidden;
+    -webkit-font-smoothing: antialiased;
 }
 
 p {
@@ -62,6 +63,13 @@ h1, h2, h3, h4, h5, h6 {
   border: none;
 }
 
+@media screen and (max-width: 768px) {
+  .wy-nav-content-wrap .wy-nav-content {
+      padding: 1em;
+  }
+}
+
+
 /*
     Code block filename style
 
@@ -105,10 +113,10 @@ h1, h2, h3, h4, h5, h6 {
 .code-block-filename + pre code {
     padding-top: 0.9em;
 }
-
+/*
 .toctree-l3 {
   border-left: 10px solid transparent;
-}
+} */
 
 /* import font awesome 4 for icons */
 @import url(https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css);
@@ -226,3 +234,84 @@ h1, h2, h3, h4, h5, h6 {
   padding-right: 0;
   margin-bottom: 0.5em;
 }
+
+/* mkdocs update theme fix-ups */
+
+.rst-content code, .rst-content tt, code {
+  /* border: none; */
+  /* background-color: #f0f1f1; */
+  color: inherit;
+}
+.rst-content pre code {
+  border: none;
+}
+
+.rst-content h1 code,
+.rst-content h2 code,
+.rst-content h3 code,
+.rst-content h4 code,
+.rst-content h5 code,
+.rst-content h6 code {
+  border: none;
+  color: inherit;
+  background-color: #f0f1f1;
+  font-size: 100%;
+}
+
+
+/* expand all the toctree entries */
+.wy-menu-vertical .toctree-l1.current .toctree-l2>ul,
+.wy-menu-vertical .toctree-l2.current .toctree-l3>ul,
+.wy-menu-vertical .toctree-l3.current .toctree-l4>ul,
+.wy-menu-vertical .toctree-l4.current .toctree-l5>ul,
+.wy-menu-vertical .toctree-l5.current .toctree-l6>ul,
+.wy-menu-vertical .toctree-l6.current .toctree-l7>ul,
+.wy-menu-vertical .toctree-l7.current .toctree-l8>ul,
+.wy-menu-vertical .toctree-l8.current .toctree-l9>ul,
+.wy-menu-vertical .toctree-l9.current .toctree-l10>ul,
+.wy-menu-vertical .toctree-l10.current .toctree-l11>ul {
+  display: block;
+}
+
+/* hide all the buttons */
+.wy-menu-vertical li.current>a button.toctree-expand,
+.wy-menu-vertical li.on a button.toctree-expand,
+.wy-menu-vertical li.toctree-l2 button.toctree-expand,
+.wy-menu-vertical li a button.toctree-expand {
+  display: none;
+}
+
+/* toctree layout improvements */
+.wy-menu-vertical a {
+  padding: 0.4em 1.2em;
+}
+.wy-menu-vertical li.current>a,
+.wy-menu-vertical li.on a {
+  font-weight: normal;
+  padding: 0.4em 1.2em;
+  /* border-right: 1px solid #f0f0f0; */
+}
+.wy-menu-vertical li.current a {
+  padding: 0.4em 1.2em;
+}
+.wy-menu-vertical li.toctree-l3 a,
+.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a {
+  padding-left: 1.8em;
+}
+.wy-menu-vertical li.toctree-l2.current>a {
+  padding: 0.4em 1.2em;
+}
+.wy-menu-vertical li.toctree-l2.current>a,
+.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a {
+  background: transparent;
+}
+.wy-menu-vertical li.toctree-l2.current>a:hover,
+.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a:hover {
+  background: #d6d6d6;
+}
+.wy-menu-vertical li.current>a.current {
+  background: #fafafa !important;
+}
+.wy-menu-vertical li.current a {
+
+}

docs/faq.md

@@ -2,6 +2,8 @@
 title: Tips and tricks
 ---
 
+# Tips and tricks
+
 ## Tips
 
 ### Linux builds in containers

docs/index.md

@@ -2,6 +2,8 @@
 title: Home
 ---
 
+# cibuildwheel
+
 {%
    include-markdown "../README.md"
    start="<!--intro-start-->"

docs/options.md

@@ -1,3 +1,5 @@
+# Options
+
 ## Setting options
 
 cibuildwheel can either be configured using environment variables, or from
@@ -1352,6 +1354,12 @@ Some options support placeholders, like `{project}`, `{package}` or `{wheel}`, t
     margin-top: 28px;
     overflow-x: auto;
   }
+  @media screen and (max-width: 768px) {
+    .options-toc {
+      grid-gap: 1em 0.5em;
+      gap: 1em 0.5em;
+    }
+  }
   .options-toc .header {
     grid-column: 1 / 3;
     font-weight: bold;

docs/setup.md

@@ -2,7 +2,9 @@
 title: 'Setup'
 ---
 
-# Run cibuildwheel locally (optional) {: #local}
+# Setup
+
+## Run cibuildwheel locally (optional) {: #local}
 
 Before getting to CI setup, it can be convenient to test cibuildwheel
 locally to quickly iterate and track down issues without even touching CI.
@@ -89,7 +91,7 @@ You should see the builds taking place. You can experiment with options using en
     cibuildwheel --platform linux
     ```
 
-## Linux builds
+### Linux builds
 
 If you've got [Docker](https://www.docker.com/products/docker-desktop) installed on
 your development machine, you can run a Linux build.
@@ -105,7 +107,7 @@ they're perfectly reproducible.
 
 The only side effect to your system will be docker images being pulled.
 
-## macOS / Windows builds
+### macOS / Windows builds
 
 Pre-requisite: you need to have native build tools installed.
 
@@ -137,9 +139,9 @@ You can override the cache folder using the ``CIBW_CACHE_PATH`` environment vari
     ```
 
 
-# Configure a CI service
+## Configure a CI service
 
-## GitHub Actions [linux/mac/windows] {: #github-actions}
+### GitHub Actions [linux/mac/windows] {: #github-actions}
 
 To build Linux, Mac, and Windows wheels using GitHub Actions, create a `.github/workflows/build_wheels.yml` file in your repo.
 
@@ -235,7 +237,7 @@ For more info on this file, check out the [docs](https://help.github.com/en/acti
 [`examples/github-deploy.yml`](https://github.com/pypa/cibuildwheel/blob/main/examples/github-deploy.yml) extends this minimal example with a demonstration of how to automatically upload the built wheels to PyPI.
 
 
-## Azure Pipelines [linux/mac/windows] {: #azure-pipelines}
+### 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.
 
@@ -249,7 +251,7 @@ Commit this file, enable building of your repo on Azure Pipelines, and push.
 
 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).
 
-## Travis CI [linux/windows] {: #travis-ci}
+### Travis CI [linux/windows] {: #travis-ci}
 
 To build Linux and Windows wheels on Travis CI, create a `.travis.yml` file in your repo.
 
@@ -265,7 +267,7 @@ Then setup a deployment method by following the [Travis CI deployment docs](http
 
 [`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.
 
-## AppVeyor [linux/mac/windows] {: #appveyor}
+### AppVeyor [linux/mac/windows] {: #appveyor}
 
 To build Linux, Mac, and Windows wheels on AppVeyor, create an `appveyor.yml` file in your repo.
 
@@ -281,7 +283,7 @@ 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}
+### CircleCI [linux/mac] {: #circleci}
 
 To build Linux and Mac wheels on CircleCI, create a `.circleci/config.yml` file in your repo,
 
@@ -298,7 +300,7 @@ Commit this file, enable building of your repo on CircleCI, and push.
 
 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}
+### Gitlab CI [linux] {: #gitlab-ci}
 
 To build Linux wheels on Gitlab CI, create a `.gitlab-ci.yml` file in your repo,
 
@@ -314,13 +316,13 @@ Gitlab will store the built wheels for you - you can access them from the Pipeli
 
 > ⚠️ Got an error? Check the [FAQ](faq.md).
 
-# Next steps
+## Next steps
 
 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).
 
 <script>
   document.addEventListener('DOMContentLoaded', function() {
-    $('a.toctree-l3, .rst-content h2').each(function(i, el) {
+    $('.toctree-l3>a, .rst-content h3').each(function(i, el) {
       var text = $(el).text()
       var match = text.match(/(.*) \[([a-z/]+)\]/);
 

docs/theme_overrides/js/theme.js

@@ -0,0 +1,271 @@
+// imported from
+// https://github.com/readthedocs/sphinx_rtd_theme/blob/bc73ad84068b4ee7d8ddae7e51f5b767e8fd377b/src/theme.js
+// modified to suit our documentation structure, to not scroll the nav sidebar
+// when clicked - this is disorienting
+
+var jQuery = window.jQuery;
+
+// Sphinx theme nav state
+function ThemeNav () {
+
+    var nav = {
+        navBar: null,
+        win: null,
+        winScroll: false,
+        winResize: false,
+        linkScroll: false,
+        winPosition: 0,
+        winHeight: null,
+        docHeight: null,
+        isRunning: false
+    };
+
+    nav.enable = function (withStickyNav) {
+        var self = this;
+
+        // TODO this can likely be removed once the theme javascript is broken
+        // out from the RTD assets. This just ensures old projects that are
+        // calling `enable()` get the sticky menu on by default. All other cals
+        // to `enable` should include an argument for enabling the sticky menu.
+        if (typeof(withStickyNav) == 'undefined') {
+            withStickyNav = true;
+        }
+
+        if (self.isRunning) {
+            // Only allow enabling nav logic once
+            return;
+        }
+
+        self.isRunning = true;
+        jQuery(function ($) {
+            self.init($);
+
+            self.reset();
+            self.win.on('hashchange', self.reset);
+
+            if (withStickyNav) {
+                // Set scroll monitor
+                self.win.on('scroll', function () {
+                    if (!self.linkScroll) {
+                        if (!self.winScroll) {
+                            self.winScroll = true;
+                            requestAnimationFrame(function() { self.onScroll(); });
+                        }
+                    }
+                });
+            }
+
+            // Set resize monitor
+            self.win.on('resize', function () {
+                if (!self.winResize) {
+                    self.winResize = true;
+                    requestAnimationFrame(function() { self.onResize(); });
+                }
+            });
+
+            self.onResize();
+        });
+
+    };
+
+    // TODO remove this with a split in theme and Read the Docs JS logic as
+    // well, it's only here to support 0.3.0 installs of our theme.
+    nav.enableSticky = function() {
+        this.enable(true);
+    };
+
+    nav.init = function ($) {
+        var doc = $(document),
+            self = this;
+
+        this.navBar = $('div.wy-side-scroll:first');
+        this.win = $(window);
+
+        // Set up javascript UX bits
+        $(document)
+            // Shift nav in mobile when clicking the menu.
+            .on('click', "[data-toggle='wy-nav-top']", function() {
+                $("[data-toggle='wy-nav-shift']").toggleClass("shift");
+                $("[data-toggle='rst-versions']").toggleClass("shift");
+            })
+
+            // Nav menu link click operations
+            .on('click', ".wy-menu-vertical .current ul li a", function() {
+                var target = $(this);
+                // Close menu when you click a link.
+                $("[data-toggle='wy-nav-shift']").removeClass("shift");
+                $("[data-toggle='rst-versions']").toggleClass("shift");
+                // Handle dynamic display of l3 and l4 nav lists
+                self.toggleCurrent(target);
+                self.hashChange();
+            })
+            .on('click', "[data-toggle='rst-current-version']", function() {
+                $("[data-toggle='rst-versions']").toggleClass("shift-up");
+            })
+
+        // Make tables responsive
+        $("table.docutils:not(.field-list,.footnote,.citation)")
+            .wrap("<div class='wy-table-responsive'></div>");
+
+        // Add extra class to responsive tables that contain
+        // footnotes or citations so that we can target them for styling
+        $("table.docutils.footnote")
+            .wrap("<div class='wy-table-responsive footnote'></div>");
+        $("table.docutils.citation")
+            .wrap("<div class='wy-table-responsive citation'></div>");
+
+        // Add expand links to all parents of nested ul
+        $('.wy-menu-vertical ul').not('.simple').siblings('a').each(function () {
+            var link = $(this);
+                expand =
+                    $('<button class="toctree-expand" title="Open/close menu"></button>');
+            expand.on('click', function (ev) {
+                self.toggleCurrent(link);
+                ev.stopPropagation();
+                return false;
+            });
+            link.prepend(expand);
+        });
+    };
+
+    nav.reset = function () {
+        // Get anchor from URL and open up nested nav
+        var anchor = encodeURI(window.location.hash) || '#';
+
+        try {
+            var vmenu = $('.wy-menu-vertical');
+            var link = vmenu.find('[href="' + anchor + '"]');
+            if (link.length === 0) {
+                // this link was not found in the sidebar.
+                // Find associated id element, then its closest section
+                // in the document and try with that one.
+                var id_elt = $('.document [id="' + anchor.substring(1) + '"]');
+                var closest_section = id_elt.closest('div.section');
+                link = vmenu.find('[href="#' + closest_section.attr("id") + '"]');
+                if (link.length === 0) {
+                    // still not found in the sidebar. fall back to main section
+                    link = vmenu.find('[href="#"]');
+                }
+            }
+            // If we found a matching link then reset current and re-apply
+            // otherwise retain the existing match
+            if (link.length > 0) {
+                $('.wy-menu-vertical .current')
+                    .removeClass('current')
+                    .attr('aria-expanded','false');
+                link.addClass('current')
+                    .attr('aria-expanded','true');
+                link.closest('li.toctree-l1')
+                    .parent()
+                    .addClass('current')
+                    .attr('aria-expanded','true');
+                for (let i = 1; i <= 10; i++) {
+                    link.closest('li.toctree-l' + i)
+                        .addClass('current')
+                        .attr('aria-expanded','true');
+                }
+
+                // EDIT by joerick
+                console.log('no scroll')
+                // link[0].scrollIntoView();
+            }
+        }
+        catch (err) {
+            console.log("Error expanding nav for anchor", err);
+        }
+
+    };
+
+    nav.onScroll = function () {
+        this.winScroll = false;
+        var newWinPosition = this.win.scrollTop(),
+            winBottom = newWinPosition + this.winHeight,
+            navPosition = this.navBar.scrollTop(),
+            newNavPosition = navPosition + (newWinPosition - this.winPosition);
+        if (newWinPosition < 0 || winBottom > this.docHeight) {
+            return;
+        }
+        this.navBar.scrollTop(newNavPosition);
+        this.winPosition = newWinPosition;
+    };
+
+    nav.onResize = function () {
+        this.winResize = false;
+        this.winHeight = this.win.height();
+        this.docHeight = $(document).height();
+    };
+
+    nav.hashChange = function () {
+        this.linkScroll = true;
+        this.win.one('hashchange', function () {
+            this.linkScroll = false;
+        });
+    };
+
+    nav.toggleCurrent = function (elem) {
+        var parent_li = elem.closest('li');
+        parent_li
+            .siblings('li.current')
+            .removeClass('current')
+            .attr('aria-expanded','false');
+        parent_li
+            .siblings()
+            .find('li.current')
+            .removeClass('current')
+            .attr('aria-expanded','false');
+        var children = parent_li.find('> ul li');
+        // Don't toggle terminal elements.
+        if (children.length) {
+            children
+                .removeClass('current')
+                .attr('aria-expanded','false');
+            parent_li
+                .toggleClass('current')
+                .attr('aria-expanded', function(i, old) {
+                    return old == 'true' ? 'false' : 'true';
+                });
+        }
+    }
+
+    return nav;
+};
+
+const ThemeNavInstance = ThemeNav();
+
+  window.SphinxRtdTheme = {
+      Navigation: ThemeNavInstance,
+      // TODO remove this once static assets are split up between the theme
+      // and Read the Docs. For now, this patches 0.3.0 to be backwards
+      // compatible with a pre-0.3.0 layout.html
+      StickyNav: ThemeNavInstance,
+  };
+
+
+// requestAnimationFrame polyfill by Erik Möller. fixes from Paul Irish and Tino Zijdel
+// https://gist.github.com/paulirish/1579671
+// MIT license
+
+(function() {
+    var lastTime = 0;
+    var vendors = ['ms', 'moz', 'webkit', 'o'];
+    for(var x = 0; x < vendors.length && !window.requestAnimationFrame; ++x) {
+        window.requestAnimationFrame = window[vendors[x]+'RequestAnimationFrame'];
+        window.cancelAnimationFrame = window[vendors[x]+'CancelAnimationFrame']
+                                   || window[vendors[x]+'CancelRequestAnimationFrame'];
+    }
+
+    if (!window.requestAnimationFrame)
+        window.requestAnimationFrame = function(callback, element) {
+            var currTime = new Date().getTime();
+            var timeToCall = Math.max(0, 16 - (currTime - lastTime));
+            var id = window.setTimeout(function() { callback(currTime + timeToCall); },
+              timeToCall);
+            lastTime = currTime + timeToCall;
+            return id;
+        };
+
+    if (!window.cancelAnimationFrame)
+        window.cancelAnimationFrame = function(id) {
+            clearTimeout(id);
+        };
+}());

mkdocs.yml

@@ -5,6 +5,9 @@ theme:
   highlightjs: true
   hljs_languages:
       - yaml
+  collapse_navigation: false
+  navigation_depth: 3
+  custom_dir: docs/theme_overrides
 repo_url: https://github.com/pypa/cibuildwheel
 edit_uri: edit/main/docs/
 
@@ -14,6 +17,7 @@ extra_css:
 extra_javascript:
   - extra.js
 
+
 nav:
   - Home: index.md
   - setup.md

setup.py

@@ -5,11 +5,10 @@ from setuptools import setup
 extras = {
     "docs": [
         "mkdocs-include-markdown-plugin==2.8.0",
-        "mkdocs==1.0.4",  # Doesn't support Python 3.10+
+        "mkdocs==1.3.1",
-        "jinja2==3.0.3",
+        "jinja2>=3.1.2",
         "pymdown-extensions",
         "mkdocs-macros-plugin",
-        "markdown<3.4",  # Breaks mkdocs 1.0.4
     ],
     "test": [
         "jinja2",