[docs] bring sphinx-click in-house for modifications

docs/sphinx/Makefile

@@ -12,6 +12,7 @@ help:
 install:
 	pip install uv
 	uv pip install -r requirements.txt
+	uv pip install -e _ext/sphinx-click
 	uv pip install -e _ext/dagster-sphinx
 	uv pip install -e _ext/sphinx-mdx-builder
 

docs/sphinx/_ext/sphinx-click/.editorconfig

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+
+root = true
+
+[*]
+indent_style = space
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+
+# Python files
+[*.py]
+indent_size = 4
+# isort plugin configuration
+known_first_party = sphinx_click
+multi_line_output = 2
+default_section = THIRDPARTY
+skip = .eggs docs
+
+# RST files (used by sphinx)
+[*.rst]
+indent_size = 3
+
+# CSS, HTML, JS, JSON, YML
+[*.{css,html,js,json,yml}]
+indent_size = 2
+
+# Matches the exact files either package.json or .travis.yml
+[{package.json,.travis.yml}]
+indent_size = 2
+
+# Dockerfile
+[Dockerfile]
+indent_size = 4
+
+# Makefile
+[Makefile]
+indent_size = 4

docs/sphinx/_ext/sphinx-click/.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## Summary
+
+<!-- Summarise your change here -->
+
+## Tasks
+
+<!-- Mark tasks as complete or not applicable using [x] -->
+
+- [ ] Added unit tests
+- [ ] Added documentation for new features (where applicable)
+- [ ] Added release notes (using [`reno`](https://pypi.org/project/reno/))
+- [ ] Ran test suite and style checks and built documentation (`tox`)
+
+## Further details
+
+<!-- Note any further details here, where applicable -->

docs/sphinx/_ext/sphinx-click/.github/workflows/ci.yaml

@@ -0,0 +1,87 @@
+---
+name: CI
+on:
+  - push
+  - pull_request
+jobs:
+  lint:
+    name: Run linters
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v3
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: python -m pip install tox
+      - name: Run tox
+        run: tox -e style
+  test:
+    name: Run unit tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v3
+        # We need history to build the package
+        with:
+          fetch-depth: 0
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install dependencies
+        run: python -m pip install tox tox-gh-actions
+      - name: Run unit tests (via tox)
+        run: tox
+  docs:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v3
+        # We need history for release notes
+        with:
+          fetch-depth: 0
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: python -m pip install tox
+      - name: Build docs (via tox)
+        run: tox -e docs
+      - name: Archive build results
+        uses: actions/upload-artifact@v3
+        with:
+          name: html-docs-build
+          path: docs/_build/html
+          retention-days: 7
+  release:
+    name: Upload release artifacts
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push'
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v3
+        # We need history to build the package
+        with:
+          fetch-depth: 0
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: python -m pip install build
+      - name: Build a binary wheel and a source tarball
+        run: python -m build --sdist --wheel --outdir dist/ .
+      - name: Publish distribution to PyPI
+        if: startsWith(github.ref, 'refs/tags')
+        uses: pypa/gh-action-pypi-publish@master
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

docs/sphinx/_ext/sphinx-click/.gitignore

@@ -0,0 +1,67 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Sphinx documentation
+docs/_build/
+
+# reno
+RELEASENOTES.rst
+releasenotes/notes/reno.cache
+
+# pbr
+AUTHORS
+ChangeLog
+
+# virtualenv
+/.venv
+
+# vim
+*.swp
+
+# Intellij
+.idea

docs/sphinx/_ext/sphinx-click/.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+# See https://pre-commit.com for more information
+---
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: mixed-line-ending
+        args: ['--fix', 'lf']
+      - id: check-byte-order-marker
+      - id: check-executables-have-shebangs
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: check-yaml
+        files: .*\.(yaml|yml)$
+      - id: check-added-large-files
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - types-docutils
+        args: ['--explicit-package-bases']
+        exclude: |
+          (?x)(
+            docs/.* \
+            | tests/.*
+          )

docs/sphinx/_ext/sphinx-click/.readthedocs.yaml

@@ -0,0 +1,15 @@
+---
+version: 2
+python:
+  install:
+    - method: pip
+      path: .
+sphinx:
+  builder: "dirhtml"
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.11"
+  jobs:
+    post_checkout:
+      - git fetch --unshallow

docs/sphinx/_ext/sphinx-click/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2017 Stephen Finucane http://that.guru/
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

docs/sphinx/_ext/sphinx-click/README.rst

@@ -0,0 +1,75 @@
+============
+sphinx-click
+============
+
+.. image:: https://github.com/click-contrib/sphinx-click/actions/workflows/ci.yaml/badge.svg
+    :target: https://github.com/click-contrib/sphinx-click/actions/workflows/ci.yaml
+    :alt: Build Status
+
+.. image:: https://readthedocs.org/projects/sphinx-click/badge/?version=latest
+    :target: https://sphinx-click.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+
+``sphinx-click`` is a `Sphinx`__ plugin that allows you to automatically extract
+documentation from a `Click-based`__ application and include it in your docs.
+
+__ http://www.sphinx-doc.org/
+__ http://click.pocoo.org/
+
+Installation
+------------
+
+Install the plugin using ``pip``:
+
+.. code-block:: shell
+
+   $ pip install sphinx-click
+
+Alternatively, install from source by cloning this repo then running ``pip``
+locally:
+
+.. code-block:: shell
+
+   $ pip install .
+
+Usage
+-----
+
+.. important::
+
+   To document a Click-based application, both the application itself and any
+   additional dependencies required by that application **must be installed**.
+
+Enable the plugin in your Sphinx ``conf.py`` file:
+
+.. code-block:: python
+
+   extensions = ['sphinx_click']
+
+Once enabled, you can now use the plugin wherever necessary in the
+documentation.
+
+.. code-block::
+
+   .. click:: module:parser
+      :prog: hello-world
+      :nested: full
+
+Detailed information on the various options available is provided in the
+`documentation <https://sphinx-click.readthedocs.io>`_.
+
+Alternative
+-----------
+
+This plugin is perfect to document a Click-based CLI in Sphinx, as it properly
+renders the help screen and its options in nice HTML with deep links and
+styling.
+
+However, if you are looking to document the source code of a Click-based CLI,
+and the result of its execution, you might want to check out `click-extra`__.
+The latter provides the ``.. click:example::`` and ``.. click:run::`` Sphinx
+directives so you can `capture and render, with full colors, the result of your
+CLI in your documentation`__.
+
+__ https://github.com/kdeldycke/click-extra/
+__ https://kdeldycke.github.io/click-extra/sphinx.html

docs/sphinx/_ext/sphinx-click/docs/changelog.rst

@@ -0,0 +1,5 @@
+Changes
+=======
+
+.. include:: ../ChangeLog
+   :start-line: 2