Unable to Build Documentation locally

Community Support
1

Hi, I’m trying to build the Sphinx Documentation locally. Everything works fine until I serve it. I get an NotImplementedError because of asyncio. After googling this, I found out that there have been some changes made to tornado due to which this error is thrown. I got a fix by including this in the “docserver.py” -

import asyncio
if sys.platform == ‘win32’:
asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())

This stops the error from occuring and the server works fine, but it gives a 404 for the all routes with “en/latest/filename” which contain the actual documentation. I am unable to solve this issue. Could someone help me out?
PS : Looks like this might be Windows Specific because of asyncio
Asyncio Issue : python 3.8 changes default asyncio loop on windows https://bugs.python.org/issue37373 · Issue #2751 · tornadoweb/tornado · GitHub
Python Version : 3.8.2

2

There is already an open PR to address the breaking change that Python 3.8 introduced on Windows. For now the simplest thing for you to do is work in a Python 3.7 environment.

3

Oh ok, I’ll try it with Python 3.7 and let you know
Thanks

4

Hey Bryan, with your suggestion, I tried building the documentation with Python 3.7.6 and I still get 404 Not Found despite the html files being built. Also, I noticed that the PR was closed so I tried it with the new code on Python 3.8.3 but the issue still persists.

5

Are you running the doc server by invoking make serve in the sphinx directory? If so, then I am afraid I don’t know. Perhaps some windows-specific issue? I have never run the docserver on windows myself, I am afraid.

6

No, the issue was that the docserver.py contains a typo in the path. It has build instead of _build. I’ll submit a PR to change this. It works fine now

7

No, the correct path is build. If things are going into a _build directory on Windows then that is the problem to fix. It should be build.

Edit: Yes, the build path is wrong on Windows:

8

So, should I change the path in “make” or “docserver”?

9

In make.bat

10

Ok, I will change that. Also, I noticed that examples aren’t loading. There seems to be no error message in the console as well. What might cause this?

11

You’ll need to be much more specific,“examples aren’t loading” could mean lots of completely different things.

12

Sorry about that, I meant that the Standalone Examples in the Gallery don’t show up, including the source code for the example too. Only the title is displayed.

13

We build the docs continuously on Linux on CI jobs, and I build frequently on OSX. I am afraid building docs on Windows is not very explored territory as none of the current core devs are regular users of Windows. I don’t really have any specific suggestions I can offer, it will require some debugging from someone who is a regular Windows user. Some places to look for information:

  • build directory output
  • sphinx build logs (can call make SPHINXOPTS=-v ... to increase verbosity)
  • browser console logs
14

Ok, it looks like there are some error messages when I try to build the documentation. I’ll try that and let you know. Thanks for the help!