docs.py

importlogging
importos
importre
importsubprocess
fromfunctoolsimportlru_cache
fromhttp.serverimportHTTPServer, SimpleHTTPRequestHandler
fromimportlibimportmetadata
frompathlibimportPath

importtyper

logging.basicConfig(level=logging.INFO)

mkdocs_name="mkdocs.yml"
en_docs_path=Path("")

app=typer.Typer()


@lru_cache
defis_mkdocs_insiders() ->bool:
version=metadata.version("mkdocs-material")
return"insiders"inversion


@app.callback()
defcallback() ->None:
ifis_mkdocs_insiders():
os.environ["INSIDERS_FILE"] ="./mkdocs.insiders.yml"
# For MacOS with insiders and Cairo
os.environ["DYLD_FALLBACK_LIBRARY_PATH"] ="/opt/homebrew/lib"


defgenerate_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)
ifnotmatch_pre:
raiseRuntimeError("Couldn't find pre section (<style>) in index.md")
frontmatter_end=match_pre.end()
new_content=content[frontmatter_end:]
# Remove content between <!-- only-mkdocs --> and <!-- /only-mkdocs -->
new_content=re.sub(
r"<!-- only-mkdocs -->.*?<!-- /only-mkdocs -->",
"",
new_content,
flags=re.DOTALL,
 )
returnnew_content


@app.command()
defgenerate_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()
defverify_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")
ifgenerated_content!=readme_content:
typer.secho(
"README.md outdated from the latest index.md", color=typer.colors.RED
 )
raisetyper.Abort()
typer.echo("Valid README ✅")


@app.command()
deflive(dirty: bool=False) ->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
args= ["mkdocs", "serve", "--dev-addr", "127.0.0.1:8008"]
ifdirty:
args.append("--dirty")
subprocess.run(args, env={**os.environ, "LINENUMS": "true"}, check=True)


@app.command()
defbuild() ->None:
"""
 Build the docs.
 """
insiders_env_file=os.environ.get("INSIDERS_FILE")
print(f"Insiders file {insiders_env_file}")
ifis_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()
defserve() ->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()