sphinx.ext.viewcode source links missing

[obestwalter]

I have the problem that sphinx.ext.viewcode sourcelinks show up in my local build (using the readthedocs theme) but not on readthedocs builds.

I am not sure if this is a bug report or a question, but I really am running out of ideas what I could be doing wrong. I am a new user of readthedocs so I might be missing something obvious, but there are other bug reports about this (1, 2) and google does not come up with much help either.

source: https://github.com/obestwalter/mau-mau (conf.py)

readthedocs project: http://readthedocs.org/projects/mau-mau/

build (from same code version where it works locally): https://readthedocs.org/projects/mau-mau/builds/3905985/

example (of not working on readthedocs): http://mau-mau.readthedocs.org/en/doc-with-sphinx/code/mau_mau/#submodules

[alimanfoo]

Also having this problem: http://zarr.readthedocs.org

[humitos]

@obestwalter last link you provided works properly to me. Was this problem fixed?

@alimanfoo it seems that sourcelinks are working properly in your build. Am I right? Do you still have this problem? What did you change to fix it?

Can I close this issue?

[obestwalter]

@humitos If you refer to my example (http://mau-mau.readthedocs.io/en/doc-with-sphinx/code/mau_mau/#submodules): no: there are no links leading to the sourcecode (or if there are some, I don't see them, or we are talking about two different things). This is no surprise either as it is still the same build.

Whether the problem is fixed now I couldn't say as I changed the docs tool and hosting the docs somewhere else (MkDocs and Github pages).

[alimanfoo]

@humitos no, there are no source links I can see (e.g., http://zarr.readthedocs.io/en/latest/api/creation.html), this is still a problem AFAIK.

[humitos]

Sorry, I got confused. I built mau-mau and zarr in my own computer and I was able to see what you mean. I have a [source] link that works properly and goes to the code.

I'm not sure why this is happening in RTD and I think we will need to research a little. If you have any suggestion or possible cause, I would appreciate.

I'm marking this as a Bug at the moment.

[alimanfoo]

Hi @humitos, thanks for following this up. I don't have any clue why this would only happen on RTD, sorry.

[axnsan12]

Hello,

I also had this problem and the source code and links started appearing after I added my src directory (which contains the directory for the package i'm documenting) to sys.path.

Before that, source links did not appear even though I was building with virtualenv and autodoc worked just fine.

[iheitlager]

That is it! since my package has the source explicitely in a source folder, I had to update conf.py with the magic redirect sys.path.insert(0, os.path.abspath('../src'))

out package contains ./src and ./docs with ./docs/conf.py (see https://github.com/schubergphilis/data-migrator/)

[stsewd]

I can see the source link working on other projects without updating the conf.py file (http://pynvim.readthedocs.io/en/latest/api/nvim.html)

So, closing this. Anyone else having this issue, feel free to ask to reopen.

[spookylukey]

@stsewd - perhaps this is to do with the .readthedocs.yml file - https://github.com/neovim/python-client/blob/master/.readthedocs.yml which is documented here - http://docs.readthedocs.io/en/latest/yaml-config.html?highlight=readthedocs.yml (once you know to look for it...)

[stsewd]

I don't think so, those settings (from the linked file) don't have anything to do with sphinx.

[spookylukey]

@stsewd - the setup_py_install setting from that file does seem to have a lot to do with sphinx and its ability to produce 'source' links. It determines whether or not to install a project before building documentation, which could make a big difference as to whether your code is importable or not, which is how sphinx.ext.viewcode works. So, for example, when I am building docs locally, if I don't do a ./setup.py install first and there are missing dependencies, when building docs the source links disappear.

Anyway, I tried with this .readthedocs.yaml file:

python:
  version: 3.5
  setup_py_install: true

And it didn't fix it for me. I also tried with exactly the same .readthedocs.yml file as the one linked, and this also didn't work.

So my projects still don't work - see for example http://parsy.readthedocs.io/en/latest/ref/primitives.html - this should have a [source] link, and it is present when I build locally with a range of Sphinx versions, but not present on readthedocs. I have tried various sys.path changes in docs/conf.py but these also don't work. It's still broken for me :-(

[stsewd]

@spookylukey I'll see if I can research a little more on your project.

[stsewd]

I wasn't able to make the source link work locally. How are you testing this?

[spookylukey]

@stsewd

mkvirtualenv --python=`which python3.5` parsy-docs-test 
git clone git@github.com:python-parsy/parsy.git
cd parsy
./setup.py develop
# (or ./setup.py install, both work)
cd docs
pip install sphinx
make html
firefox _build/html/ref/primitives.html

This worked with the repo as it was. To make it easier, I've just explicitly [re-added]( a 'sys.path' change to the docs/conf.py file, and now you don't need to do ./setup.py develop (but it doesn't harm if you do). I've pushed my change to sys.path but it still doesn't work on RTD - http://parsy.readthedocs.io/en/latest/ref/primitives.html

[stsewd]

@spookylukey hey, I just saw that there is a source link now :)

[spookylukey]

OK, I see that now. There must have been some caching because it wasn't there before, meaning I'm not sure which thing finally fixed it. (I've just realised there is a revision number at the bottom of the docs pages which helps check whether you've got the latest version!).

In this case, I think the fixes must have been:

1. a .readthedocs.yml file that enabled Python 3 (without which I'm probably getting import errors, since this project is Python 3 only)
2. having the sys.path.insert hack explicitly in the docs/conf.py. My project is different from the one you linked in that the source lives in project_root/src, not project_root, which could be the difference here.

In addition, I've just tried with another project, which has dependencies that need to be installed for the code to be importable. For this case, I also needed to add a .readthedocs.yml file with:

python:
  setup_py_install: true

Thanks for your help, hope this helps other people!

[RudolfCardinal]

I'm also having this problem: https://whiskerpythonclient.readthedocs.io/ . A local build shows the [source] links, but the RTD version doesn't. The project is configured to use setup.py install via the web interface, and has identical RTD settings (except also enabling "Give the virtual environment access to the global site-packages dir", because it looks for numpy) as https://cardinalpythonlib.readthedocs.io/ -- which works.

Things that have not worked:

• restricting setup.py to Python 3.5
• changing the Sphinx theme to classic
• poking the source directory into sys.path as described here

It's puzzling...

[spookylukey]

@RudolfCardinal
My current .readthedocs.yml file, which works for my case, is:

build:
  image: latest

python:
  version: 3.6
  setup_py_install: true

In addition I have the sys.path hacking in docs/conf.py