运行mkdocs serve命令触发NotImplementedError的原因及解决方法

I'm trying to build docs with MkDocs on Windows 10, using Python 3.8.0a3. When I run mkdocs serve, I hit a NotImplementedError with the following traceback:

INFO - Building documentation...
INFO - Cleaning site directory
[I 190419 16:50:46 server:298] Serving on http://127.0.0.1:8000
Traceback (most recent call last):
File "c:\python38\lib\runpy.py", line 192, in _run_module_as_main
return _run_code(code, main_globals, None,
File "c:\python38\lib\runpy.py", line 85, in _run_code
exec(code, run_globals)
File "C:\Python38\Scripts\mkdocs.exe\__main__.py", line 9, in <module>
File "c:\python38\lib\site-packages\click\core.py", line 764, in __call__
return self.main(*args, **kwargs)
File "c:\python38\lib\site-packages\click\core.py", line 717, in main
rv = self.invoke(ctx)
File "c:\python38\lib\site-packages\click\core.py", line 1137, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
File "c:\python38\lib\site-packages\click\core.py", line 956, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "c:\python38\lib\site-packages\click\core.py", line 555, in invoke
return callback(*args, **kwargs)
File "c:\python38\lib\site-packages\mkdocs\__main__.py", line 128, in serve_command
serve.serve(
File "c:\python38\lib\site-packages\mkdocs\commands\serve.py", line 124, in serve
_livereload(host, port, config, builder, site_dir)
File "c:\python38\lib\site-packages\mkdocs\commands\serve.py", line 58, in _livereload
server.serve(root=site_dir, host=host, port=port, restart_delay=0)
File "c:\python38\lib\site-packages\livereload\server.py", line 300, in serve
self.application(
File "c:\python38\lib\site-packages\livereload\server.py", line 255, in application
app.listen(port, address=host)
File "c:\python38\lib\site-packages\tornado\web.py", line 2112, in listen
server.listen(port, address)
File "c:\python38\lib\site-packages\tornado\tcpserver.py", line 152, in listen
self.add_sockets(sockets)
File "c:\python38\lib\site-packages\tornado\tcpserver.py", line 165, in add_sockets
self._handlers[sock.fileno()] = add_accept_handler(
File "c:\python38\lib\site-packages\tornado\netutil.py", line 279, in add_accept_handler
io_loop.add_handler(sock, accept_handler, IOLoop.READ)
File "c:\python38\lib\site-packages\tornado\platform\asyncio.py", line 99, in add_handler
self.asyncio_loop.add_reader(fd, self._handle_events, fd, IOLoop.READ)
File "c:\python38\lib\asyncio\events.py", line 498, in add_reader
raise NotImplementedError
NotImplementedError

I'm looking for the root cause and a fix for this issue.

Hey there, let's break down what's happening and get your MkDocs server up and running smoothly again.

Root Cause #

The core issue is your Python version: Python 3.8.0a3 is an unfinished alpha pre-release. Early alpha builds often have unimplemented or buggy APIs, and in this case, the asyncio.add_reader() method (which Tornado—MkDocs' underlying livereload server—depends on) wasn't fully implemented for Windows. When MkDocs tries to spin up the livereload server, it hits this missing functionality and throws the NotImplementedError.

Fixes to Try #

Here are three reliable solutions, ordered from most recommended to quick temporary workaround:

• Upgrade to a stable Python 3.8 release
  Python 3.8.0's official stable version (and all subsequent 3.8.x patches) fixed this Windows asyncio gap. Uninstall your 3.8.0a3 build, grab a stable 3.8.x release (like 3.8.10, the last maintained version in the 3.8 series), reinstall MkDocs and its dependencies, and the error should vanish.

• Switch to Python 3.7.x
  If you don't want to adjust your Python 3.8 setup, Python 3.7 has fully mature asyncio support on Windows and works flawlessly with MkDocs. Just switch your environment to a 3.7.x version, reinstall MkDocs, and you'll be good to go.

• Run MkDocs without livereload
  For a quick fix, skip the livereload feature entirely by running this command:

  mkdocs serve --no-livereload
  

  This bypasses the Tornado code path causing the error, so you can still preview your docs—you'll just need to manually refresh the page when you make changes.

内容的提问来源于stack exchange，提问作者Anthony