sphinx docs not rendering properly locally but works in readthedocs

Skip to first unread message

Shahzeb Siddiqui

Oct 21, 2021, 6:09:01 PM10/21/21
to sphinx-users

I have a sphinx build for buildtest project https://github.com/buildtesters/buildtest which is not rendering properly when i build the docs however they work in readthedocs which are done automatically through PR preview you can see for instance this PR https://github.com/buildtesters/buildtest/pull/917 has this readthedocs build https://buildtest--917.org.readthedocs.build/en/917/.

On my local machine i am just running 

make html
open _build/html/index.html

I would appreciate if anyone knows how to work around this issue. I can confirm there are no warnings in the build. 

I have tried recreating my python environment with all the deps to ensure this is not some bug in a library. I was going to try a different machine to see if this build works on other machine. I tried building a different project that is hosted on readthedocs and I can confirm the issue is specific to this project.

Screen Shot 2021-10-21 at 6.04.00 PM.png

Kevin Sheppard

Oct 21, 2021, 6:11:58 PM10/21/21
to sphinx...@googlegroups.com

You need to locally host your site in a webserver and then navigate through your webserver to the page.  Browsers won’t load some files from file:// URIs.  If you open your host in the same directory, then you would need to navigate to http://localhost/_build/html/index.html.



You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/ec30c418-943c-4abe-bd6a-b69fd5ee60f0n%40googlegroups.com.


Shahzeb Siddiqui

Dec 7, 2021, 11:41:11 AM12/7/21
to sphinx-users
Hi Kevin,

I tried a different solution by using the following anchor in my Makefile so i can do 'make view'

        python -m http.server --directory _build/html/ 9000

Then when i run it i still get same issue. I have tried building other readthedocs project and I didnt have any issue. I am wondering if someone can reproduce this on your system. I have tried building the docs locally in the readthedocs container and this resulted in same issue. Whats odd it works on readthedocs server but just doesn't work locally. There are no warnings that indicate why this output looks messed up. 

Here is me running the docs server locally

(buildtest) bash-3.2$ make view
make: Circular Makefile <- Makefile dependency dropped.
python -m http.server --directory _build/html/ 9000
Serving HTTP on port 9000 ( ...

The steps to reproduce this would be as follows

1. git clone this repo: git clone https://github.com/buildtesters/buildtest.git
2. setup a python environment
python3 -m venv $HOME/buildtest 
source $HOME/buildtest/activate 
cd buildtest source setup.sh

3. Install dev dependencies

pip install -r docs/requirements.txt

4. build docs

make html
make view

Then you can navigate to your localhost at 9000 port and see the docs.

I would appreciate your help
Screen Shot 2021-12-07 at 11.37.47 AM.png
Reply all
Reply to author
0 new messages