🔧 Update MkDocs configs and docs build setup (#900)

.github/workflows/build-docs.yml

@@ -67,13 +67,10 @@ jobs:
         with:
           key: mkdocs-cards-${{ github.ref }}-v1
           path: .cache
+      - name: Verify README
+        run: python ./scripts/docs.py verify-readme
       - name: Build Docs
-        if: github.event_name == 'pull_request' && github.secret_source != 'Actions'
-        run: python -m mkdocs build
-      - name: Build Docs with Insiders
-        if: ( github.event_name != 'pull_request' || github.secret_source == 'Actions' )
-        run: python -m mkdocs build --config-file mkdocs.insiders.yml
-
+        run: python ./scripts/docs.py build
       - uses: actions/upload-artifact@v4
         with:
           name: docs-site

docs/index.md

@@ -1,3 +1,7 @@
+<style>
+.md-content .md-typeset h1 { display: none; }
+</style>
+
 <p align="center">
   <a href="https://typer.tiangolo.com"><img src="https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg" alt="Typer"></a>
 </p>

mkdocs.insiders.yml

@@ -1,4 +1,3 @@
-INHERIT: mkdocs.yml
 plugins:
   social:
   typeset:

mkdocs.maybe-insiders.yml

@@ -0,0 +1,6 @@
+# Define this here and not in the main mkdocs.yml file because that one could be auto
+# updated and written, and the script would remove the env var
+INHERIT: !ENV [INSIDERS_FILE, './mkdocs.no-insiders.yml']
+markdown_extensions:
+  pymdownx.highlight:
+    linenums: !ENV [LINENUMS, false]

mkdocs.yml

@@ -1,3 +1,4 @@
+INHERIT: ./mkdocs.maybe-insiders.yml
 site_name: Typer
 site_description: Typer, build great CLIs. Easy to code. Based on Python type hints.
 site_url: https://typer.tiangolo.com/
@@ -136,6 +137,5 @@ extra_css:
   - css/custom.css
 
 extra_javascript:
-  - https://unpkg.com/mermaid@8.4.6/dist/mermaid.min.js
   - js/termynal.js
   - js/custom.js

scripts/docs.py

@@ -0,0 +1,130 @@
+import logging
+import os
+import re
+import subprocess
+from functools import lru_cache
+from http.server import HTTPServer, SimpleHTTPRequestHandler
+from importlib import metadata
+from pathlib import Path
+
+import mkdocs.commands.build
+import mkdocs.commands.serve
+import mkdocs.config
+import mkdocs.utils
+import typer
+
+logging.basicConfig(level=logging.INFO)
+
+mkdocs_name = "mkdocs.yml"
+en_docs_path = Path("")
+
+app = typer.Typer()
+
+
+@lru_cache
+def is_mkdocs_insiders() -> bool:
+    version = metadata.version("mkdocs-material")
+    return "insiders" in version
+
+
+@app.callback()
+def callback() -> None:
+    if is_mkdocs_insiders():
+        os.environ["INSIDERS_FILE"] = "./mkdocs.insiders.yml"
+    # For MacOS with insiders and Cairo
+    os.environ["DYLD_FALLBACK_LIBRARY_PATH"] = "/opt/homebrew/lib"
+
+
+def generate_readme_content() -> str:
+    en_index = en_docs_path / "docs" / "index.md"
+    content = en_index.read_text("utf-8")
+    match_pre = re.search(r"</style>\n\n", content)
+    if not match_pre:
+        raise RuntimeError("Couldn't find pre section (<style>) in index.md")
+    frontmatter_end = match_pre.end()
+    new_content = content[frontmatter_end:]
+    return new_content
+
+
+@app.command()
+def generate_readme() -> None:
+    """
+    Generate README.md content from main index.md
+    """
+    typer.echo("Generating README")
+    readme_path = Path("README.md")
+    new_content = generate_readme_content()
+    readme_path.write_text(new_content, encoding="utf-8")
+
+
+@app.command()
+def verify_readme() -> None:
+    """
+    Verify README.md content from main index.md
+    """
+    typer.echo("Verifying README")
+    readme_path = Path("README.md")
+    generated_content = generate_readme_content()
+    readme_content = readme_path.read_text("utf-8")
+    if generated_content != readme_content:
+        typer.secho(
+            "README.md outdated from the latest index.md", color=typer.colors.RED
+        )
+        raise typer.Abort()
+    typer.echo("Valid README ✅")
+
+
+@app.command()
+def live() -> None:
+    """
+    Serve with livereload a docs site for a specific language.
+
+    This only shows the actual translated files, not the placeholders created with
+    build-all.
+
+    Takes an optional LANG argument with the name of the language to serve, by default
+    en.
+    """
+    # Enable line numbers during local development to make it easier to highlight
+    os.environ["LINENUMS"] = "true"
+    mkdocs.commands.serve.serve(dev_addr="127.0.0.1:8008")
+
+
+@app.command()
+def build() -> None:
+    """
+    Build the docs.
+    """
+    insiders_env_file = os.environ.get("INSIDERS_FILE")
+    print(f"Insiders file {insiders_env_file}")
+    if is_mkdocs_insiders():
+        print("Using insiders")
+    print("Building docs")
+    subprocess.run(["mkdocs", "build"], check=True)
+    typer.secho("Successfully built docs", color=typer.colors.GREEN)
+
+
+@app.command()
+def serve() -> None:
+    """
+    A quick server to preview a built site.
+
+    For development, prefer the command live (or just mkdocs serve).
+
+    This is here only to preview the documentation site.
+
+    Make sure you run the build command first.
+    """
+    typer.echo("Warning: this is a very simple server.")
+    typer.echo("For development, use the command live instead.")
+    typer.echo("This is here only to preview the documentation site.")
+    typer.echo("Make sure you run the build command first.")
+    os.chdir("site")
+    server_address = ("", 8008)
+    server = HTTPServer(server_address, SimpleHTTPRequestHandler)
+    typer.echo("Serving at: http://127.0.0.1:8008")
+    server.serve_forever()
+
+
+if __name__ == "__main__":
+    app()

scripts/test-files.sh

@@ -3,8 +3,6 @@
 set -e
 set -x
 
-# Check README.md is up to date
-diff --brief docs/index.md README.md
 # Check copy paste errors in tutorials
 if grep -r --include "*.md" "Usage: tutorial" ./docs ; then echo "Incorrect console demo"; exit 1 ; fi
 if grep -r --include "*.md" "python tutorial" ./docs ; then echo "Incorrect console demo"; exit 1 ; fi