From ca7b92b267093d7fd116dd6facda46b08e50c5d7 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 20 Feb 2026 14:46:58 +0000 Subject: [PATCH] Use mkdocs2 for documentation builds --- .github/workflows/docs.yml | 28 +++++++ .gitignore | 2 +- README.md | 10 --- docs/templates/base.html | 10 ++- mkdocs.toml | 6 ++ requirements.txt | 4 +- scripts/docs | 153 ------------------------------------- 7 files changed, 44 insertions(+), 169 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 mkdocs.toml delete mode 100755 scripts/docs diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..6de5b3c --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,28 @@ +name: Documentation +on: + push: + branches: + - dev +permissions: + contents: read + pages: write + id-token: write +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - uses: actions/configure-pages@v5 + - uses: actions/checkout@v5 + - uses: actions/setup-python@v5 + with: + python-version: 3.x + - run: pip install -r requirements.txt + - run: mkdocs build + - uses: actions/upload-pages-artifact@v4 + with: + path: site + - uses: actions/deploy-pages@v4 + id: deployment diff --git a/.gitignore b/.gitignore index f9d43a1..65f9ba1 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,4 @@ __pycache__/ dist/ venv/ -build/ +site/ diff --git a/README.md b/README.md index f6f9926..4f88bbc 100644 --- a/README.md +++ b/README.md @@ -59,14 +59,4 @@ The [HTTPX 1.0 design proposal](https://www.encode.io/httpnext/) is now availabl --- -# Collaboration - -The repository for this project is currently private. - -We’re looking at creating paid opportunities for working on open source software *which are properly compensated, flexible & well balanced.* - -If you're interested in a position working on this project, please send an intro. - ---- -

This provisional design work is not currently licensed for reuse.
Designed & crafted with care.
— 🦋 —

diff --git a/docs/templates/base.html b/docs/templates/base.html index 22fe4d3..64c57f4 100644 --- a/docs/templates/base.html +++ b/docs/templates/base.html @@ -86,6 +86,12 @@ color: #474747; } + h1 a, h2 a, h3 a, h4 a { + color: #eee; + font-weight: 300; + text-decoration: none; + } + h1 { text-align: center; font-weight: 300; font-size: 4rem; } h2 { font-size: 2rem; } h3 { font-size: 1.5rem; } @@ -174,7 +180,7 @@
- {{ content }} + {{ page.html }}
- \ No newline at end of file + diff --git a/mkdocs.toml b/mkdocs.toml new file mode 100644 index 0000000..407b0bc --- /dev/null +++ b/mkdocs.toml @@ -0,0 +1,6 @@ +[mkdocs] +nav = [] + +[loaders] +theme = "dir://docs" +docs = "dir://docs" diff --git a/requirements.txt b/requirements.txt index f4d4bb3..8fd226d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -12,6 +12,4 @@ pytest-cov==6.1.1 unasync==0.6.0 # Documentation... -click==8.2.1 -jinja2==3.1.6 -markdown==3.8 +git+https://github.com/encode/mkdocs.git diff --git a/scripts/docs b/scripts/docs deleted file mode 100755 index 8c53da4..0000000 --- a/scripts/docs +++ /dev/null @@ -1,153 +0,0 @@ -#!venv/bin/python -import pathlib -import posixpath - -import click -import ghp_import -import logging -import httpx -import jinja2 -import markdown - -import xml.etree.ElementTree as etree - - -pages = { - '/': 'docs/index.md', - '/quickstart': 'docs/quickstart.md', - '/clients': 'docs/clients.md', - '/servers': 'docs/servers.md', - '/requests': 'docs/requests.md', - '/responses': 'docs/responses.md', - '/urls': 'docs/urls.md', - '/headers': 'docs/headers.md', - '/content-types': 'docs/content-types.md', - '/streams': 'docs/streams.md', - '/connections': 'docs/connections.md', - '/parsers': 'docs/parsers.md', - '/networking': 'docs/networking.md', - '/about': 'docs/about.md', -} - -def path_to_url(path): - if path == "index.md": - return "/" - return f"/{path[:-3]}" - - -class URLsProcessor(markdown.treeprocessors.Treeprocessor): - def __init__(self, state): - self.state = state - - def run(self, root: etree.Element) -> etree.Element: - for element in root.iter(): - if element.tag == 'a': - key = 'href' - elif element.tag == 'img': - key = 'src' - else: - continue - - url_or_path = element.get(key) - if url_or_path is not None: - output_url = self.rewrite_url(url_or_path) - element.set(key, output_url) - - return root - - def rewrite_url(self, href: str) -> str: - if not href.endswith('.md'): - return href - - current_url = path_to_url(self.state.file) - linked_url = path_to_url(href) - return posixpath.relpath(linked_url, start=current_url) - - -class BuildState: - def __init__(self): - self.file = '' - - -state = BuildState() -env = jinja2.Environment( - loader=jinja2.FileSystemLoader('docs/templates'), - autoescape=False -) -template = env.get_template('base.html') -md = markdown.Markdown(extensions=['fenced_code']) -md.treeprocessors.register( - item=URLsProcessor(state), - name='urls', - priority=10, -) - - -def not_found(): - text = httpx.Text('Not Found') - return httpx.Response(404, content=text) - - -def web_server(request): - if request.url.path not in pages: - return not_found() - - file = pages[request.url.path] - text = pathlib.Path(file).read_text() - - state.file = file - content = md.convert(text) - html = template.render(content=content).encode('utf-8') - content = httpx.HTML(html) - return httpx.Response(200, content=html) - - -@click.group() -def main(): - pass - - -@main.command() -def build(): - pathlib.Path("build").mkdir(exist_ok=True) - - for url, path in pages.items(): - basename = url.lstrip("/") - output = f"build/{basename}.html" if basename else "build/index.html" - text = pathlib.Path(path).read_text() - content = md.convert(text) - html = template.render(content=content) - pathlib.Path(output).write_text(html) - print(f"Built {output}") - - -@main.command() -def serve(): - logging.basicConfig( - format="%(levelname)s [%(asctime)s] %(name)s - %(message)s", - datefmt="%Y-%m-%d %H:%M:%S", - level=logging.INFO - ) - - with httpx.serve_http(web_server) as server: - server.wait() - - -@main.command() -def deploy(): - ghp_import.ghp_import( - "build", - mesg="Documentation deploy", - remote="origin", - branch="gh-pages", - push=True, - force=False, - use_shell=False, - no_history=False, - nojekyll=True, - ) - print(f"Deployed to GitHub") - - -if __name__ == "__main__": - main()