add broken link check to docs, fix multi builder howto, uberify the c…

…heck script and run it in CI

.github/workflows/test.yml

@@ -41,11 +41,7 @@ jobs:
           poetry install -E html -E png -E pdf
       - name: Run Static Analysis
         run: |
-          poetry run ruff format sphinxcontrib/typer
-          poetry run ruff check --fix --select I sphinxcontrib/typer
-          poetry run ruff check sphinxcontrib/typer
-          poetry check
-          poetry run pip check
+          ./check.sh --no-fix
           poetry run python -m readme_renderer ./README.md
 
   build:

CONTRIBUTING.md

@@ -40,12 +40,7 @@ or warnings where justified is acceptable:
 
 
 ```bash
-poetry run ruff format sphinxcontrib/typer
-poetry run ruff check --fix --select I sphinxcontrib/typer
-poetry run ruff check sphinxcontrib/typer
-poetry check
-poetry run pip check
-poetry run python -m readme_renderer ./README.md
+./check.sh
 ```
 
 

check.sh

@@ -1,5 +1,30 @@
-poetry run ruff format sphinxcontrib/typer
-poetry run ruff check --fix --select I sphinxcontrib/typer
-poetry run ruff check --fix sphinxcontrib/typer
-poetry check
-poetry run pip check
+set -e  # Exit immediately if a command exits with a non-zero status.
+
+echox() {
+    echo "\033[34m$@\033[0m"  # Manually echo the command
+    "$@" | while IFS= read -r line; do echo "  \033[32m$line\033[0m"; done
+}
+
+if [ "$1" == "--no-fix" ]; then
+    echox poetry run ruff format --check
+    echox poetry run ruff check --select I
+    echox poetry run ruff check
+else
+    echox poetry run ruff format
+    echox poetry run ruff check --fix --select I
+    echox poetry run ruff check --fix
+fi
+
+echox poetry check
+echox poetry run pip check
+cd ./doc
+echox poetry run doc8 --ignore-path build --max-line-length 100 -q
+set +e  # Turn off the -e flag to allow the sphinx-build command to fail.
+# check for broken links in the docs ############
+echox poetry run sphinx-build -b linkcheck -q -D linkcheck_timeout=5 ./source ./build > /dev/null 2>&1
+if [ $? -ne 0 ]; then
+    cat ./build/output.txt
+    exit 1
+fi
+#################################################
+cd ..

doc/source/conf.py

@@ -2,6 +2,7 @@
 import sys
 from pathlib import Path
 from sphinxcontrib import typer as sphinxcontrib_typer
+import shutil
 
 # Configuration file for the Sphinx documentation builder.
 #
@@ -64,3 +65,7 @@
 latex_engine = 'xelatex'
 
 typer_get_web_driver = 'web_driver.typer_get_web_driver'
+
+def setup(app):
+    if app.doctreedir.exists():
+        shutil.rmtree(app.doctreedir)

doc/source/howto.rst

@@ -20,23 +20,21 @@ different formats (e.g. html, pdf or text). This causes problems with the way th
 directive dynamically determines which render target to use based on the active builder.
 This can mean that if you run sphinx-build for html and latexpdf at the same time the
 pdf may not render all typer helps as expected. To work around this you can do one of
-three things
+four things
 
 1. Run sphinx-build for each format separately.
 2. Use the `only directive <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-only>`_
    in combination with :ref:`:preferred: <directive_options>` to specify builder specific content.
 3. Use the `--fresh-env <https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-E>`_
    option to force sphinx to rebuild the directive output for each builder.
+4. Add the following code to your conf.py to remove the doctree between builders:
 
-If also building a PDF on `readthedocs <https://readthedocs.org/>`_ you can do 3 by adding the
-following to your readthedocs.yml:
+    .. code-block:: python
 
-.. code-block:: yaml
-
-    sphinx:
-        configuration: path/to/conf.py
-        extra_build_args:
-            - "--fresh-env"
+        def setup(app):
+            import shutil
+            if app.doctreedir.exists():
+                shutil.rmtree(app.doctreedir)
 
 
 Change the Width

sphinxcontrib/typer/__init__.py

@@ -65,7 +65,7 @@ def get_function(function: t.Union[str, t.Callable[..., t.Any]]):
     if callable(function):
         return function
     if isinstance(function, str):
-        parts = function.split('.')
+        parts = function.split(".")
         return getattr(import_module(".".join(parts[0:-1])), parts[-1])
 
 
@@ -489,15 +489,19 @@ def get_console(stderr: bool = False) -> Console:
             png_path = Path(self.env.app.builder.outdir) / (
                 f'{normal_cmd.replace(":", "_")}_{self.uuid(normal_cmd)}.png'
             )
-            get_function(self.env.app.config.typer_convert_png)(self, rendered, png_path)
+            get_function(self.env.app.config.typer_convert_png)(
+                self, rendered, png_path
+            )
             section += nodes.image(
                 uri=os.path.relpath(png_path, Path(self.env.srcdir)),
                 alt=source_name,
             )
         elif self.target == RenderTarget.HTML:
             section += nodes.raw(
                 "",
-                get_function(self.env.app.config.typer_render_html)(self, normal_cmd, rendered),
+                get_function(self.env.app.config.typer_render_html)(
+                    self, normal_cmd, rendered
+                ),
                 format="html",
             )
         elif self.target == RenderTarget.SVG:
@@ -645,7 +649,9 @@ def typer_get_iframe_height(
     if cache["iframe_heights"].get(normal_cmd):
         return cache["iframe_heights"][normal_cmd]
 
-    with get_function(directive.env.app.config.typer_get_web_driver)(directive) as driver:
+    with get_function(directive.env.app.config.typer_get_web_driver)(
+        directive
+    ) as driver:
         # use base64 to avoid issues with special characters
         driver.get(
             f'data:text/html;base64,'
@@ -843,7 +849,9 @@ def typer_convert_png(
     from selenium.webdriver.common.by import By
 
     tag = "code"
-    with get_function(directive.env.app.config.typer_get_web_driver)(directive) as driver:
+    with get_function(directive.env.app.config.typer_get_web_driver)(
+        directive
+    ) as driver:
         with tempfile.NamedTemporaryFile(suffix=".html") as tmp:
             if directive.target is RenderTarget.TEXT:
                 tag = "pre"
@@ -907,9 +915,13 @@ def setup(app: application.Sphinx) -> t.Dict[str, t.Any]:
     # Need autodoc to support mocking modules
     app.add_directive("typer", TyperDirective)
 
-    app.add_config_value("typer_render_html", "sphinxcontrib.typer.typer_render_html", "env")
+    app.add_config_value(
+        "typer_render_html", "sphinxcontrib.typer.typer_render_html", "env"
+    )
 
-    app.add_config_value("typer_get_iframe_height", "sphinxcontrib.typer.typer_get_iframe_height", "env")
+    app.add_config_value(
+        "typer_get_iframe_height", "sphinxcontrib.typer.typer_get_iframe_height", "env"
+    )
     app.add_config_value("typer_svg2pdf", "sphinxcontrib.typer.typer_svg2pdf", "env")
     app.add_config_value("typer_iframe_height_padding", 30, "env")
     app.add_config_value(
@@ -918,8 +930,12 @@ def setup(app: application.Sphinx) -> t.Dict[str, t.Any]:
         "env",
     )
 
-    app.add_config_value("typer_convert_png", "sphinxcontrib.typer.typer_convert_png", "env")
-    app.add_config_value("typer_get_web_driver", "sphinxcontrib.typer.typer_get_web_driver", "env")
+    app.add_config_value(
+        "typer_convert_png", "sphinxcontrib.typer.typer_convert_png", "env"
+    )
+    app.add_config_value(
+        "typer_get_web_driver", "sphinxcontrib.typer.typer_get_web_driver", "env"
+    )
 
     return {
         "parallel_read_safe": True,

tests/click/complex/complex/commands/cmd_init.py

@@ -12,5 +12,6 @@ def cli(ctx, path):
         path = ctx.home
     ctx.log(f"Initialized the repository in {click.format_filename(path)}")
 
+
 if __name__ == "__main__":
     cli()

tests/click/complex/complex/commands/cmd_status.py

@@ -2,6 +2,7 @@
 
 import click
 
+
 @click.command("status", short_help="Shows file changes.")
 @pass_environment
 def cli(ctx):

tests/click/conf.py

@@ -19,22 +19,24 @@
     if path.is_dir():
         sys.path.append(str(path))
 
-TEST_CALLBACKS = Path(__file__).parent / 'callback_record.json'
+TEST_CALLBACKS = Path(__file__).parent / "callback_record.json"
 
 test_callbacks = {}
 
+
 def record_callback(callback):
     """crude but it works"""
     if TEST_CALLBACKS.is_file():
         os.remove(TEST_CALLBACKS)
     test_callbacks[callback] = True
     TEST_CALLBACKS.write_text(json.dumps(test_callbacks))
 
+
 # -- Project information -----------------------------------------------------
 
-project = 'SphinxContrib Typer Tests'
-copyright = f'2023-{datetime.now().year}, Brian Kohan'
-author = 'Brian Kohan'
+project = "SphinxContrib Typer Tests"
+copyright = f"2023-{datetime.now().year}, Brian Kohan"
+author = "Brian Kohan"
 
 # The full version, including alpha/beta/rc tags
 release = sphinxcontrib_typer.__version__
@@ -45,13 +47,10 @@ def record_callback(callback):
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-    'sphinx_rtd_theme',
-    'sphinxcontrib.typer'
-]
+extensions = ["sphinx_rtd_theme", "sphinxcontrib.typer"]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -64,7 +63,7 @@ def record_callback(callback):
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = "alabaster"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -76,30 +75,31 @@ def record_callback(callback):
 ###########################################################
 # Test our typer configuration parameter function overrides
 
+
 def typer_render_html(*args, **kwargs):
-    record_callback('typer_render_html')
+    record_callback("typer_render_html")
     return sphinxcontrib_typer.typer_render_html(*args, **kwargs)
 
 
 def typer_get_iframe_height(*args, **kwargs):
-    record_callback('typer_get_iframe_height')
+    record_callback("typer_get_iframe_height")
     return sphinxcontrib_typer.typer_get_iframe_height(*args, **kwargs)
 
 
 def typer_svg2pdf(*args, **kwargs):
-    record_callback('typer_svg2pdf')
+    record_callback("typer_svg2pdf")
     return sphinxcontrib_typer.typer_svg2pdf(*args, **kwargs)
 
 
 def typer_convert_png(*args, **kwargs):
-    record_callback('typer_convert_png')
+    record_callback("typer_convert_png")
     return sphinxcontrib_typer.typer_convert_png(*args, **kwargs)
 
 
 def typer_get_web_driver(*args, **kwargs):
-    record_callback('typer_get_web_driver')
+    record_callback("typer_get_web_driver")
     return sphinxcontrib_typer.typer_get_web_driver(*args, **kwargs)
 
 
 typer_iframe_height_padding = 40
-typer_iframe_height_cache_path = Path(__file__).parent / 'cache.json'
+typer_iframe_height_cache_path = Path(__file__).parent / "cache.json"

tests/click/inout/inout.py

@@ -18,7 +18,7 @@ def cli(input, output):
     ```bash
         inout foo.txt bar.txt -
     ```
-    
+
     Write stdin into the file foo.txt
     ```bash
         inout - foo.txt

tests/click/termui/termui.py

@@ -168,5 +168,6 @@ def menu():
         elif menu == "quit":
             return
 
+
 if __name__ == "__main__":
     cli()