GeezerVison is showing github.com — Building the docs · Issue #31 · pybind/python_example
DescriptionHi,
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. Reacted by Benjamin F. Maier, Bendik Samseth, Nick Konz and Arthur Wesley Activitybsamseth commented on Mar 8, 2019 I still have this issue, exactly as described above. Does anyone know how to fix this? benmaier commented on Mar 8, 2019 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 commented on Mar 8, 2019 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 commented on Mar 8, 2019 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 commented on Mar 8, 2019 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 commented on Mar 8, 2019 am2222 commented on Jun 8, 2019 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 commented on Jun 15, 2019 am2222 commented on Jun 16, 2019 @williamfgc Seems we need to focus on building on read the docs but their system does not have much abilities to build libraries williamfgc commented on Jun 16, 2019 @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 commented on Jun 17, 2019 @williamfgc thanks, seems I have to move my package to anaconda too, benmaier commented on Jun 17, 2019 @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. Reacted by William F Godoy am2222 commented on Jun 19, 2019 @benmaier Can you show me how you configured RTD to make and install your package? Mine has a problem with installing pybind benmaier commented on Jun 19, 2019 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 commented on Jun 19, 2019 @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. Reacted by Benjamin F. Maier nickk124 commented on Jun 18, 2020 @bsamseth how did you edit your Makefile specifically to get this to work? I'm still having the same issue on macOS Catalina. bsamseth commented on Jun 21, 2020
@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):
|
SPHINXBUILD = sphinx-build |
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|
