Sphinx: docstring following autofunction:: does not update

[sephib]

I'm trying to contribute to the dask documentation

Problem

• Updating the docstring in the method doesn't update.

Procedure to reproduce the problem

Using python anaconda distribution I ran the following environment. Then ran

make html

I also used added the set SPHINXOPTS=-vvv to the make.bat file. Unfortunately the -w option did not produce a log file so it was of limited use.

Error logs / results

The docstring was not updated.
for example changing the docstring READ_DOC_TEMPLATE in the csv.py file

Expected results

The docstring should be updated in the relevant place

Environment info

• OS: Win7 64bit
• Python version: 3.6
• Sphinx version: v1.5.6

[tk0miya]

I don't know conda. So could you check some points in your environment please?
1) a path of the python file you editted
2) a path of the module which python imported

Usually, sphinx refers the docstring from installed python file instead of the file on local directory. Because autodoc imports the module to fetch its docstring.

[sephib]

Hi,
Yes - that was the problem! the make html did not use the local files from the git project, but rather the files from the python interpreter installations.

Is there a way to configure the sphinx to use the files from the project local directory?

[jfbu]

Is there a way to configure the sphinx to use the files from the project local directory?

You could try in this case

sys.path.insert(0, os.path.abspath('../../'))

in conf.py.

Or go to top repertory and run pip install -e . while in your conda environment (I expect this will then shadow the installed dask module in conda environment with your own edits later on.) Perhaps you can do that rather in a virtualenv (not using conda), but I don't know though if pip install -e . will automatically install all dependencies for this project.

[sephib]

Thx!
The sys.path... did the job.

[sephib]

BTW -
I've updated the conf.py with

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx',
              'sphinx.ext.autosummary', 'sphinx.ext.extlinks', 'numpydoc']
intersphinx_mapping = {'pandas': ('http://pandas.pydata.org/pandas-docs/stable/',  
                                  'http://pandas.pydata.org/pandas-docs/stable/objects.inv')}

However I've failed to generate an external link from within the docstring . In the csv.py file I've tried various options from this post but all failed. The only option that generated a link was this but it was invalid

:pd:meth:`pandas.{reader}`

'dask/docs/build/html/dataframe-api.html#id1'

any ideas? should I open a different issue?

[sephib]

Well it seems that the issue is with the identifying the types in the http://pandas.pydata.org/pandas-docs/stable/objects.inv since :meth:pandas.DataFrame.apply generates a valid link