Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Python 3.6: autodoc page builds locally, but is empty on readthedocs.org #3634

Closed
patdaburu opened this issue Feb 18, 2018 · 14 comments
Closed
Labels
Support Support question

Comments

@patdaburu
Copy link

Details

Expected Result

I am attempting to build documentation for my project. When I build locally, autodoc produces API documentation, so I would expect that the same result on readthedocs.org, or that inspecting the build output for the project would reveal errors.

Actual Result

No API documentation is generated and no errors (that I can detect) are displayed.

Additional Information

I now have two "active" branches for the project, "latest" and "Conda". (I am using "Conda" for experimentation.)

I have tried a number of things, including:

  • mocking the imports in conf.py
  • removing all the install_requires from my setup.py
  • adding a .readthedocs.yml file

I've spent a fair amount of time looking at the posts of others with similar problems, but have been unable to find a remedy and without some indication as to why the build is failing in the Builds tab, I'm not sure what else to try.

Below is the output from one of the builds:

conda env create --name conda --file /home/docs/checkouts/readthedocs.org/user_builds/djio/checkouts/conda/environment.yml
conda install --yes --name conda mock pillow sphinx sphinx_rtd_theme
python /home/docs/checkouts/readthedocs.org/user_builds/djio/conda/conda/bin/pip install -U --cache-dir /home/docs/checkouts/readthedocs.org/user_builds/djio/.cache/pip recommonmark readthedocs-sphinx-ext
cat docs/source/conf.py
python /home/docs/checkouts/readthedocs.org/user_builds/djio/conda/conda/bin/sphinx-build -T -E -b readthedocs -d _build/doctrees-readthedocs -D language=en . _build/html
python /home/docs/checkouts/readthedocs.org/user_builds/djio/conda/conda/bin/sphinx-build -T -b json -d _build/doctrees-json -D language=en . _build/json
python /home/docs/checkouts/readthedocs.org/user_builds/djio/conda/conda/bin/sphinx-build -T -b readthedocssinglehtmllocalmedia -d _build/doctrees-readthedocssinglehtmllocalmedia -D language=en . _build/localmedia
python /home/docs/checkouts/readthedocs.org/user_builds/djio/conda/conda/bin/sphinx-build -b latex -D language=en -d _build/doctrees . _build/latex
pdflatex -interaction=nonstopmode /home/docs/checkouts/readthedocs.org/user_builds/djio/checkouts/conda/docs/source/_build/latex/djio.tex
makeindex -s python.ist djio.idx
pdflatex -interaction=nonstopmode /home/docs/checkouts/readthedocs.org/user_builds/djio/checkouts/conda/docs/source/_build/latex/djio.tex
mv -f /home/docs/checkouts/readthedocs.org/user_builds/djio/checkouts/conda/docs/source/_build/latex/djio.pdf /home/docs/checkouts/readthedocs.org/user_builds/djio/artifacts/conda/sphinx_pdf/djio.pdf
python /home/docs/checkouts/readthedocs.org/user_builds/djio/conda/conda/bin/sphinx-build -T -b epub -d _build/doctrees-epub -D language=en . _build/epub
mv -f /home/docs/checkouts/readthedocs.org/user_builds/djio/checkouts/conda/docs/source/_build/epu

@stsewd
Copy link
Member

stsewd commented Feb 18, 2018

Please provide the build url or the RTD project page.

@patdaburu
Copy link
Author

Thanks for your reply. I apologize for not including that information with my original post.

The build URL is: https://readthedocs.org/projects/djio/builds/6766175/
The RTD project page that corresponds is: http://djio.readthedocs.io/en/conda/

Again, many thanks!

@stsewd
Copy link
Member

stsewd commented Feb 19, 2018

@patdaburu did you try marking the "Install Project" option on advanced settings? or putting this on your .readthedocs.yml file

python:
   setup_py_install: true

@patdaburu
Copy link
Author

Thank you for this suggestion. I had not tried this, but have now tried it both ways with no apparent change. My project does have a tricky dependency (GDAL) which was, I think, originally causing the builds to fail all together. Since the build still apparently passes (https://readthedocs.org/projects/djio/builds/6768637/) I'm not entirely sure what to look for, but I will go back and make sure my package installs correctly in some other environments now that I've made
so many changes.

@stsewd
Copy link
Member

stsewd commented Feb 19, 2018

Now this error is shown on your build

/home/docs/checkouts/readthedocs.org/user_builds/djio/checkouts/conda/docs/source/api.rst:12: WARNING: autodoc: failed to import module 'djio.geometry'; the following exception was raised:
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/djio/conda/conda/lib/python3.6/site-packages/sphinx/ext/autodoc.py", line 658, in import_object
    __import__(self.modname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/djio/checkouts/conda/djio/geometry.py", line 17, in <module>
    from geoalchemy2.types import WKBElement, WKTElement`

Looks like a problem with your dependencies, if this depends of a c module, you can check https://docs.readthedocs.io/en/latest/faq.html#i-get-import-errors-on-libraries-that-depend-on-c-modules

@patdaburu
Copy link
Author

This is supremely helpful! I feel foolish asking this for fear that it's obvious, but I'm just not sure where I would go to see this output. I am currently mocking the external modules (I had included geoalchemy2, but I think I now understand I needed to add geoalchemy2.types specifically, along with some others). That said, I still see the same result, though the build just indicates that it passed (https://readthedocs.org/projects/djio/builds/6771860/). Could I ask where I should be looking to see a stack trace like the one you posted? I think that would help me get the rest of the way to a resolution.

Many thanks once again!

@stsewd
Copy link
Member

stsewd commented Feb 19, 2018

@patdaburu Don't worry about asking questions :). And yes, the build is shown as successful because no error happened, but on the sphinx step (6th command) you can see some warnings.

Currently you need to scroll a little to see the warnings, I'm working or a PR to see the raw log (#3585)

screenshot-2018-2-19 djio read the docs

@patdaburu
Copy link
Author

Thank you again! It took a while for me to work out the source of the warnings which seems to have been mocking the typing library. Things seem to be working well now: http://djio.readthedocs.io/en/latest/api.html#module-djio.geometry

Thanks again for your help!!

@willronchetti
Copy link

willronchetti commented Dec 20, 2019

@patdaburu did you try marking the "Install Project" option on advanced settings? or putting this on your .readthedocs.yml file

python:
   setup_py_install: true

For anyone looking at this, in the new version of the .readthedocs.yml file you would need to specify the install requirements like below (and not how stated above unless you're using the old version). See here.

python:
  install:
    - requirements: requirements.txt

@patdaburu
Copy link
Author

With apologies for the delayed response: I did use the setup_py_install option in .readthedocs.yaml. There haven't been any updates to this project in a while, but the docs seem to be in working order.

build:
    image: latest

python:
    version: 3.6
    setup_py_install: true

conda:
    file: environment.yml

@pradyunsg
Copy link

For folks who aren't using a setup.py file -- eg: if you're using anything that's a modern alternative to setuptools, like flit -- you can add the relevant directory to sys.path in the conf.py file.

As an example, if you follow the src/ layout for structuring your package:

import os
import sys
import pathlib

if "READTHEDOCS" in os.environ:
    src_folder = pathlib.Path(__file__).resolve().parent.parent / "src"
    sys.path.append(str(src_folder))

    print("Detected running on ReadTheDocs")
    print(f"Added {src_folder} to sys.path")

@astrojuanlu
Copy link
Contributor

@pradyunsg Wouldn't the solution here be installing with pip instead, so any backend just works? Or am I missing anything?

@pradyunsg
Copy link

pradyunsg commented May 20, 2021

That'd work well if RTD supported installing a path with pip! It didn't work the last time I checked. 😅

Update: it's supported in the configuration file!

    - method: pip
      path: .
      extra_requirements:
        - docs 

@astrojuanlu
Copy link
Contributor

For email subscribers: it is indeed supported :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Support Support question
Projects
None yet
Development

No branches or pull requests

6 participants