3

I have this python package that I'd like to automatically document using Sphinx. I've inserted docstrings in every functions and classes.

I made an account on ReadTheDocs, and did the setup accordingly (i.e., a docs/ dir with a conf.py file). Then, basically, I've tried almost everything: every combination of autodoc::, autofunction::, autoclass::; I tried using the same conf.py file as other packages which documented API (with specific changes made according to my case, of course); but it just doesn't work, the API page remains inexorably empty...

mzjn
  • 48,958
  • 13
  • 128
  • 248
Dominique Makowski
  • 1,511
  • 1
  • 13
  • 30
  • And if you go to the build page in RTD (`https://readthedocs.org/projects//builds/`), do you get any feedback there? How did you generate `api.rst`? I find this useful for initial setup: https://jeffknupp.com/blog/2013/08/16/open-sourcing-a-python-project-the-right-way/ – jonrsharpe Nov 15 '16 at 17:55
  • Thanks for this very helpful link! However, even though I tried reproducing these steps and tried building up the documentation from scratch, it still doesn't show anything. Worst part is, when I run the makefile (using the command `make html`, it shows no particular error and nothing related to the package I'm trying to document...). I just can't figure out why! As to my `api.rst` file, it was generated only by creating a rst doc and inserting some `..autoclass::` directives. Anyway thank you for your answer! – Dominique Makowski Nov 17 '16 at 09:55
  • That might be the problem, have you considered getting Sphinx to generate the docs rather than trying to do it yourself? – jonrsharpe Nov 17 '16 at 09:58

1 Answers1

1

Try to add this to your conf.py :

########### TRICK FOUND ON SOME TUTORIAL : ADD IN THE MOCK_MODULES ANY EXTERNAL MODULE YOU'RE USING IN YOUR PACKAGE.

import mock

MOCK_MODULES = ['numpy', 'scipy', 'sklearn', 'matplotlib', 'matplotlib.pyplot', 'scipy.interpolate', 'scipy.special', 'math', '__future__', 'toolboxutilities']
for mod_name in MOCK_MODULES:
    sys.modules[mod_name] = mock.Mock()

In the MOCK_MODULES, add any single external import that your project uses. I had exactly the same problem and this solved it.

Also in the conf.py, don't forget to add the :

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

In your case you already have it but I mention it in case someone else with the same problem would see my answer.

Guillaume
  • 51
  • 7