1

I am very new to read the docs. I have a documentation folder docs in my github repo created using Sphinx in my local machine. I tried to link the docs to Read the Docs.

From settings of the repo I added the read the docs service.

From Read the Docs website I imported the project.

But, the documentation in read the docs only shows the front page of index.html file. When I click any links all are empty. However, in my local machine all the links are text in it.

My github repo is this: github repo

My ReadTheDocs link is : readthedocs docs

File Structure

  • docs
    • html
    • rst
      ** conf.py
    • source
    • Makefile
  • src

The main page of index.html

The main page of index.html

In my machine when I click first link it has contents

enter image description here

In readthedocs website when I click first link it is EMPTY

enter image description here

Note that the whole repo is same in both github website and my local machine.
All the files in computer are uploaded in github, but still readthedocs only can not find the documentation.

Question: How can we show the contents of links in ReadTheDocs ?

What am I doing wrong?
Is there a way to fix the problem or RTD only shows the front page?

Simple Test:
We can download the repo (5Mb) and run index.html which shows contents inside a0_interpolate_flux link, but if we click the same link in readthedocs given above it does not show any docstring contents.

Update
I have googled a lot and also tried read the docs website, but to no avail. I wonder how the same HTML page opens differently in local machine and readthedocs webhost?

Some related links are following:

[1]: https://stackoverflow.com/questions/41029181/read-the-docs-not-updating-with-new-files?rq=1

bad_coder
  • 11,289
  • 20
  • 44
  • 72
BhishanPoudel
  • 15,974
  • 21
  • 108
  • 169

1 Answers1

2

You need to tell RTD to install your package. See RTD FAQ My project isn’t building with autodoc.

If you look at your RTD build history, and expand the third bar, you will see the import errors.

To fix it:

  1. Configure the RTD Admin to use a virtual environment and install your package, using a requirements.txt file.
  2. Create a requirements.txt file and push it to your repo, specifying your project's requirements, itself included.
Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • Thanks, however, I looked at build history it says build completed with green highlight, I can see no errors. – BhishanPoudel Jul 26 '17 at 02:20
  • I will follow the instructions from admin tab of readthedocs and will update the question if I still get the error, Thanks Steve. – BhishanPoudel Jul 26 '17 at 02:22
  • @BhishanPoudel as, I said before you need to *expand the third bar* to see the import errors. Builds can complete *with errors*. To fix it, you need to do *both* 1 and 2 in my answer. – Steve Piercy Jul 26 '17 at 09:11
  • Sorry for the update, however, whatever I tried RTD fails, I uploaded requirements.txt with all required libraries, still it fails. – BhishanPoudel Jul 27 '17 at 01:56
  • Why does it fail? What is the error message when you expand the third bar, as I mentioned previously? – Steve Piercy Jul 27 '17 at 08:40
  • Here RTD is successful to import the **docs** from Github. But the problem is when I click the links it opens empty links, nothing is there except the module name. However, If i download the **docs** folder form Github to my laptop and open docs/html/index.html and I click the links to the modules it opens all the docstrings. I have uploaded the pictures above in the question. – BhishanPoudel Jul 27 '17 at 16:45
  • I have also uploaded **requirements.txt** file in main repo and gave the paths in admin section of RTD. RTD has no compilation errors but only shows the front page of index.html. when i click any link, nothing is there. – BhishanPoudel Jul 27 '17 at 16:52
  • Relevant locations are docs/rst/conf.py and docs/Makefile and docs/html/index.html – BhishanPoudel Jul 27 '17 at 16:55
  • Visit: http://readthedocs.org/projects/psf-creation-for-phosim/builds/5751842/ Then click the grey bars of any command to expand the log for that command. In this case, the fifth grey bar reveals errors and a stacktrace with several import errors that you will need to remedy. Other grey bars indicate similar issues. For your local docs, your package is installed correctly and is importable, so of course docs build correctly. Now you must make it reproducible on RTD. Suggest reproducing the install and docs build locally in a clean separate virtual environment first to save time. – Steve Piercy Jul 27 '17 at 19:58
  • Apologies for bugging, I tried to solve the bugs, in the RTD logsfile it says module not found, but in the github all the modules are there. If you can graciously spare some time, will you suggest what should I change in ADMIN Advanced Settings of RTD ? So that I can solve this issue. This issue is taking A LOT of my time. Thanks a lot. – BhishanPoudel Jul 28 '17 at 00:28
  • I again updated sphinx directories, docs/source/conf.py; docs/Makefile; docs/build/html/index.html; and all the scripts are in REPO/psf_creation – BhishanPoudel Jul 28 '17 at 00:32
  • And it still fails. – BhishanPoudel Jul 28 '17 at 00:32
  • As I suggested previously, reproduce the install and docs build of your package locally in a clean separate virtual environment to save time instead of thrashing around with RTD. Use `pip install -r requirements.txt`, which mimics RTD when it installs a project and its requirements. If none of that helps, I suggest learning from an a known working project. Fork and clone Pyramid https://github.com/pylons/pyramid. Set up a project on RTD to build its docs. The requirements file is named `rtd.txt` and uses `pip install -e .[docs]` to install the docs requirements in `setup.py`. – Steve Piercy Jul 28 '17 at 03:37