Building the docs

[fbartolic]

Hi,

I can build the docs with Sphinx using make html but when I open the html files I can't see any of the function docstrings. I'm new to Sphinx so I might be missing something.

[ghost]

I have the same problem when I try to build the docs. I do get some warnings from the doc generator (see below).

How am I supposed to build it?

C:\github\python_example\docs>.\make.bat html
Running Sphinx v1.7.6
making output directory...
loading pickled environment... done
[autosummary] generating autosummary for: index.rst, python_example.rst
Failed to import 'python_example': no module named python_example
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 2 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] python_example
WARNING: autodoc: failed to import module 'python_example'; the following exception was raised:
No module named 'python_example'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] python_example
C:\github\python_example\docs\index.rst:6: WARNING: toctree contains reference to document 'python_example' that doesn't have a title: no link will be generated
C:\github\python_example\docs\index.rst:6: WARNING: toctree contains reference to document 'python_example' that doesn't have a title: no link will be generated
C:\github\python_example\docs\index.rst:6: WARNING: toctree contains reference to document 'python_example' that doesn't have a title: no link will be generated
generating indices... genindexC:\github\python_example\docs\index.rst:6: WARNING: toctree contains reference to document 'python_example' that doesn't have a title: no link will be generated

writing additional pages... searchC:\github\python_example\docs\index.rst:6: WARNING: toctree contains reference to document 'python_example' that doesn't have a title: no link will be generated

copying static files... WARNING: html_static_path entry 'C:\\github\\python_example\\docs\\_static' does not exist
done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 7 warnings.

The HTML pages are in _build\html.

Build finished. The HTML pages are in _build/html.

[bsamseth]

I still have this issue, exactly as described above. Does anyone know how to fix this?

[benmaier]

did you install python_example with pip? The warning implies that Python wants to import the package but can't and as such the docstrings cannot be created

[bsamseth]

~~I ran cloned the repo, then ran python setup.py develop successfully from within a fresh virtual environment. Should be equivalent to running pip install -e ., no? Is there some different way I should have done it for sphinx to find it?~~ Never mind, confused that with a different repo I tried similarly. Trying to run setup after a clone here fails due to no module named pybind11.

Could you say what steps one should take in order for the docs to build as they should? Trying to get this to work for my own project, with similar results, except it runs without any warnings about not finding the module.

[benmaier]

I now tried to replicate with a freshly cloned repo. somehow running python setup.py develop does not seem to be enough for the package to be importable. After running pip -e install ../python_example, building the docs with make html works

[bsamseth]

I still had issues, even after running pip install -e . and/or python setup.py develop. Found the issue to be that sphinx-build pointed to something in /usr/local/bin, and not to the active virtualenv. Editing the Makefile to point to the correct sphinx fixed it. Sorry to bother with this, turned out to be my fault (surprise!).

[benmaier]

Cool, glad it works now!

[am2222]

Hi, I have the same problem, with the fact that it only shows one of my functions when I build it on local machine. when I deploy it on readthedocs website it does not show that function even. IS there any way to find what is wrong with my methods?

[williamfgc]

@am2222 I have the same issue, I believe the parser needs to find the generated python module in your PYTHONPATH. See related issue in pybind11.

[am2222]

@williamfgc Seems we need to focus on building on read the docs but their system does not have much abilities to build libraries

[williamfgc]

@am2222 FYI, I'm looking into their recent, still experimental, readthedocs support for conda. Sounds like a good alternative to building, as it pulls your packages from conda directly.

[am2222]

@williamfgc thanks, seems I have to move my package to anaconda too,

[benmaier]

@williamfgc you're correct that sphinx has to find the package in the PYTHONPATH in order to work. It is, however, usually sufficient to install your package with pip which then includes it in the PYTHONPATH, too.

I've tried using RTD for my library. You can configure their system to pull from your repository and install via pip which means that it is locally built on their virtual machine and then sphinx is run on that machine. You have to make sure that their virtual machine has a C++11-compliant compiler, which worked for me. However, their machines do have limited RAM (I think 1GB). In my library, I've worked quite a lot with template function which take a lot of RAM during compilation and so building failed and as such, building the docs failed, as well. I've settled for local generation of the docs with make html and upload it to my own web server.

RTD provides access to their log files so if building fails you can check them to find out more about the problem.

[am2222]

@benmaier Can you show me how you configured RTD to make and install your package? Mine has a problem with installing pybind

[benmaier]

my package is this one: https://github.com/benmaier/tacoma

you need to have a completely set up subdirectory named docs, like so: https://github.com/benmaier/tacoma/tree/master/docs

In this subdirectory, you need to have a file docs/requirements.txt in which the crucial dependencies for your package are listed. Mine looks like this:

pip==18.0
pybind11==2.2.3
sphinxcontrib-katex==0.3

I have a lot of other dependencies which do not really matter to build the docstrings, so you have to add those as MOCK_MODULES in Sphinx's docs/conf.py. Looks like this in my docs:

...
from mock import Mock as MagicMock

class Mock(MagicMock):
    @classmethod
    def __getattr__(cls, name):
            return Mock()

MOCK_MODULES = ['numpy', 'scipy', 'matplotlib', 'matplotlib.pyplot', 'matplotlib.collections',
                'lmfit', 'networkx', 'community', 
                'scipy.optimize', 'scipy.stats', 'scipy.special', 'scipy.integrate',
                'scipy.sparse', 'scipy.sparse.linalg', 'scipy.linalg',
                'numpy.polynomial', 'numpy.polynomial.polynomial', 'wget',
                'lmfit',
               ]
...

On RTD, go to Admin > Advanced Settings and put docs/requirements.txt in the field Requirements file. Also, check the boxes Install Project and Use system packages.

If a build on RTD fails, go to Builds, click on the latest build attempt and then click View raw to see the whole log file and to see what went wrong.

Also, you can set up a docs/.readthedocs.yml to automate all this, I think, see https://docs.readthedocs.io/en/stable/config-file/v2.html . I have not done that, though.

[williamfgc]

@benmaier thanks for the explanation and providing insight for your own process. I recently had to tweak the requirements.txt file to point at fixed versions, not all version were compatible (some breathe update). Thanks, this is very helpful.

[nickk124]

@bsamseth how did you edit your Makefile specifically to get this to work? I'm still having the same issue on macOS Catalina.

[bsamseth]

@bsamseth how did you edit your Makefile specifically to get this to work? I'm still having the same issue on macOS Catalina.

It has been a while, so not 100% sure what I did. But reading my own comments, I believe I edited the Makefile to use a full path to sphinx-build. I.e use the full path to the correct version executable on this line (something like /path/to/repo/my-venv/bin/sphinx-build): https://github.com/pybind/python_example/blob/4a08067caf2fb2200a6c2106249a61d023dcf05d/docs/Makefile#L6