prompt: You will be provided with a partial code base and an issue statement explaining a problem to resolve.
  <issue>
  Building MkDocs' documentation
  When I began working on #3493 I needed to be able to run the dev server with MkDocs' own documentation, which was more difficult than it should have been.
  
  First, let me say that I always work from a venv, and created a new one to start my work. In the past, one could simply do `pip install -r requirements/docs.txt` and then `mkdocs serve` and it worked.  But I had to jump through a lot of hoops and learn new tools to get things working this time.
  
  To be clear, I am not suggesting that the old tools should be brought back. Nor am I suggesting that my preferred tools be used. However, I could find no documentation about how to proceed. Eventually, I did find documentation that hatch is used for tests, and looking at `pyproject.toml` I could see a config for a hatch `docs` env. But not having ever used that tool before, it took be multiple tries (and searches) to work out how to even use that env. But, I'm getting ahead of myself...
  
  After realizing that there were no requirements.txt files, I next looked for optional dependencies defined in `pyproject.toml`. I was hoping to maybe do `pip install .[docs]` (`.` rather than `markdown` because I was working from the working tree of the git repo). When I determined that that wasn't an option, I began looking into the hatch options. Finally in some random question in some forum I found an explanation of how to run the `shell` subcommand with an alternate env: `hatch -e docs shell`.
  
  And then I could finally run `mkdocs serve`. Except that I got an error about missing `po` files, which is weird because I am using English, which should work without any translations being defined. Finally, after generating `po` and `mo` files, I could run the dev server and begin my work.
  
  All of this led me to believe that the current maintainers are not ever running the dev server with MkDocs documentation. And I also could not find any automations for deploying the documentation, so I couldn't even use that as a reference.
  
  Again, I am not being critical of the tool choices. I see that a switch was made from tox to hatch. That's fine if that is the tool that the maintainers what to use. But for an occasional contributor, I would prefer to not need to learn these tools. I would prefer to be able to use standard Python tools that work with any project. Or if I do need to use your tool of choice, then I would expect the specific commands I would need to use to all be documented clearly.
  
  I could submit a PR which updated the documentation, but I'm not sure what the recommended best practices are here. I am simply bringing this to the attention of the maintainers with the hopes that more consideration will be given to this in the future.
  
  </issue>
  <code>
  [start of docs/hooks.py]
  1 import re
  2 from pathlib import Path
  3 
  4 from mkdocs.config.defaults import MkDocsConfig
  5 from mkdocs.structure.nav import Page
  6 
  7 
  8 def _get_language_of_translation_file(path: Path) -> str:
  9     with path.open(encoding='utf-8') as f:
  10         translation_line = f.readline()
  11     m = re.search('^# (.+) translations ', translation_line)
  12     assert m
  13     return m[1]
  14 
  15 
  16 def on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, **kwargs):
  17     if page.file.src_uri == 'user-guide/choosing-your-theme.md':
  18         here = Path(config.config_file_path).parent
  19 
  20         def replacement(m: re.Match) -> str:
  21             lines = []
  22             for d in sorted(here.glob(m[2])):
  23                 lang = _get_language_of_translation_file(Path(d, 'LC_MESSAGES', 'messages.po'))
  24                 lines.append(f'{m[1]}`{d.name}`: {lang}')
  25             return '\n'.join(lines)
  26 
  27         return re.sub(
  28             r'^( *\* )\(see the list of existing directories `(.+)`\)$',
  29             replacement,
  30             markdown,
  31             flags=re.MULTILINE,
  32         )
  33
  [end of docs/hooks.py]
  </code>
  
  I need you to solve this issue by generating a single patch file that I can apply directly to this repository using git apply. Please respond with a single patch file in the following format.
  <patch>
  diff --git a/file.py b/file.py
  --- a/file.py
  +++ b/file.py
  @@ -1,27 +1,35 @@
   def euclidean(a, b):
  -    while b:
  -        a, b = b, a % b
  -    return a
  +    if b == 0:
  +        return a
  +    return euclidean(b, a % b)
   
   
   def bresenham(x0, y0, x1, y1):
       points = []
       dx = abs(x1 - x0)
       dy = abs(y1 - y0)
  -    sx = 1 if x0 < x1 else -1
  -    sy = 1 if y0 < y1 else -1
  -    err = dx - dy
  +    x, y = x0, y0
  +    sx = -1 if x0 > x1 else 1
  +    sy = -1 if y0 > y1 else 1
   
  -    while True:
  -        points.append((x0, y0))
  -        if x0 == x1 and y0 == y1:
  -            break
  -        e2 = 2 * err
  -        if e2 > -dy:
  -            err -= dy
  -            x0 += sx
  -        if e2 < dx:
  -            err += dx
  -            y0 += sy
  +    if dx > dy:
  +        err = dx / 2.0
  +        while x != x1:
  +            points.append((x, y))
  +            err -= dy
  +            if err < 0:
  +                y += sy
  +                err += dx
  +            x += sx
  +    else:
  +        err = dy / 2.0
  +        while y != y1:
  +            points.append((x, y))
  +            err -= dx
  +            if err < 0:
  +                x += sx
  +                err += dy
  +            y += sy
  +
  +    points.append((x, y))
       return points
  
  </patch>
golden_diff: diff --git a/docs/hooks.py b/docs/hooks.py
  --- a/docs/hooks.py
  +++ b/docs/hooks.py
  @@ -1,8 +1,12 @@
  +from __future__ import annotations
  +
   import re
   from pathlib import Path
  +from typing import TYPE_CHECKING
   
  -from mkdocs.config.defaults import MkDocsConfig
  -from mkdocs.structure.nav import Page
  +if TYPE_CHECKING:
  +    from mkdocs.config.defaults import MkDocsConfig
  +    from mkdocs.structure.nav import Page
   
   
   def _get_language_of_translation_file(path: Path) -> str:
  @@ -13,7 +17,7 @@
       return m[1]
   
   
  -def on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, **kwargs):
  +def on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, **kwargs) -> str | None:
       if page.file.src_uri == 'user-guide/choosing-your-theme.md':
           here = Path(config.config_file_path).parent
  
verification_info: {"golden_diff": "diff --git a/docs/hooks.py b/docs/hooks.py\n--- a/docs/hooks.py\n+++ b/docs/hooks.py\n@@ -1,8 +1,12 @@\n+from __future__ import annotations\n+\n import re\n from pathlib import Path\n+from typing import TYPE_CHECKING\n \n-from mkdocs.config.defaults import MkDocsConfig\n-from mkdocs.structure.nav import Page\n+if TYPE_CHECKING:\n+    from mkdocs.config.defaults import MkDocsConfig\n+    from mkdocs.structure.nav import Page\n \n \n def _get_language_of_translation_file(path: Path) -> str:\n@@ -13,7 +17,7 @@\n     return m[1]\n \n \n-def on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, **kwargs):\n+def on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, **kwargs) -> str | None:\n     if page.file.src_uri == 'user-guide/choosing-your-theme.md':\n         here = Path(config.config_file_path).parent\n", "issue": "Building MkDocs' documentation\nWhen I began working on #3493 I needed to be able to run the dev server with MkDocs' own documentation, which was more difficult than it should have been.\r\n\r\nFirst, let me say that I always work from a venv, and created a new one to start my work. In the past, one could simply do `pip install -r requirements/docs.txt` and then `mkdocs serve` and it worked.  But I had to jump through a lot of hoops and learn new tools to get things working this time.\r\n\r\nTo be clear, I am not suggesting that the old tools should be brought back. Nor am I suggesting that my preferred tools be used. However, I could find no documentation about how to proceed. Eventually, I did find documentation that hatch is used for tests, and looking at `pyproject.toml` I could see a config for a hatch `docs` env. But not having ever used that tool before, it took be multiple tries (and searches) to work out how to even use that env. But, I'm getting ahead of myself...\r\n\r\nAfter realizing that there were no requirements.txt files, I next looked for optional dependencies defined in `pyproject.toml`. I was hoping to maybe do `pip install .[docs]` (`.` rather than `markdown` because I was working from the working tree of the git repo). When I determined that that wasn't an option, I began looking into the hatch options. Finally in some random question in some forum I found an explanation of how to run the `shell` subcommand with an alternate env: `hatch -e docs shell`.\r\n\r\nAnd then I could finally run `mkdocs serve`. Except that I got an error about missing `po` files, which is weird because I am using English, which should work without any translations being defined. Finally, after generating `po` and `mo` files, I could run the dev server and begin my work.\r\n\r\nAll of this led me to believe that the current maintainers are not ever running the dev server with MkDocs documentation. And I also could not find any automations for deploying the documentation, so I couldn't even use that as a reference.\r\n\r\nAgain, I am not being critical of the tool choices. I see that a switch was made from tox to hatch. That's fine if that is the tool that the maintainers what to use. But for an occasional contributor, I would prefer to not need to learn these tools. I would prefer to be able to use standard Python tools that work with any project. Or if I do need to use your tool of choice, then I would expect the specific commands I would need to use to all be documented clearly.\r\n\r\nI could submit a PR which updated the documentation, but I'm not sure what the recommended best practices are here. I am simply bringing this to the attention of the maintainers with the hopes that more consideration will be given to this in the future.\n", "before_files": [{"content": "import re\nfrom pathlib import Path\n\nfrom mkdocs.config.defaults import MkDocsConfig\nfrom mkdocs.structure.nav import Page\n\n\ndef _get_language_of_translation_file(path: Path) -> str:\n    with path.open(encoding='utf-8') as f:\n        translation_line = f.readline()\n    m = re.search('^# (.+) translations ', translation_line)\n    assert m\n    return m[1]\n\n\ndef on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, **kwargs):\n    if page.file.src_uri == 'user-guide/choosing-your-theme.md':\n        here = Path(config.config_file_path).parent\n\n        def replacement(m: re.Match) -> str:\n            lines = []\n            for d in sorted(here.glob(m[2])):\n                lang = _get_language_of_translation_file(Path(d, 'LC_MESSAGES', 'messages.po'))\n                lines.append(f'{m[1]}`{d.name}`: {lang}')\n            return '\\n'.join(lines)\n\n        return re.sub(\n            r'^( *\\* )\\(see the list of existing directories `(.+)`\\)$',\n            replacement,\n            markdown,\n            flags=re.MULTILINE,\n        )\n", "path": "docs/hooks.py"}]}