CODEWITHSUNDEEP
pythonpython-sphinx
Jon
Jon

Reputation: 12954

Sphinx does not document all classes

I am trying to use Sphinx for my documentation. Surprisingly, it works with some classes and modules and for some not.

Below you can find a source file and .rst file where sphinx does not add the class.

I use the Sphinx 'sphinx.ext.autodoc' extension.

Why Sphinx does not add my class to the documentation? How can I debug Sphinx in such cases?

My Sphinx file: my_project.analyzers.content_ascii.rst

my_project.analyzers.content_ascii package
==========================================

Submodules
----------

my_project.analyzers.content_ascii.wl_redo_detect_date module
--------------------------------------------------------------

.. automodule:: my_project.analyzers.content_ascii.wl_redo_detect_date
    :members:
    :undoc-members:
    :show-inheritance:


Module contents
---------------

.. automodule:: my_project.analyzers.content_ascii
    :members:
    :undoc-members:
    :show-inheritance:

Code file: __init__.py

#!/usr/bin/python
# -*- coding: utf-8 -*-
'''
Created on Jan 24, 2014

@author: me
'''

from some_other_project.file_tools import execute_string    
from my_project.analyzers import Analyzer    
from other_project.handler.Handler import Handler

TARGET_ENCODING = 'utf-8'

class ExtractContentAscii(Analyzer):
    '''

    Further improvements: do this and that.
    '''

    def __init__(self):
        Analyzer.__init__(self)

# ...

Upvotes: 0

Views: 3845

Answers (2)

hokiegeek2
hokiegeek2

Reputation: 303

Adding this element was critical for me:

:show-inheritance:

Without this, I had two modules where no classes were being picked up, and 3 other modules where seemingly random classes were ignored.

Upvotes: 2

Jon
Jon

Reputation: 12954

I realized that Sphinx needs all dependencies in order to create a documentation. Not just all other projects in your workspace. Even external projects need to be available in the path like celery or django.

In order to fix that issue:

1) Add all dependencies from your workspace to your path e.g in your Sphinx's config.py:

import os
import sys

def add_to_path():

    partial_path = os.path.join(os.path.dirname(os.path.realpath(__file__)), '../../')
    workspace_path = os.path.abspath(partial_path)
    assert os.path.exists(workspace_path)

    projects = []

    for current, dirs, c in os.walk(str(workspace_path)):
        for dir in dirs:

            project_path = os.path.join(workspace_path, dir, 'src')

            if os.path.exists(project_path):
                projects.append(project_path)

    for project_str in projects:
        sys.path.append(project_str)

add_to_path()

2) Check that all your necessary outer dependencies are installed on the system. A good way to handle these dependencies is a setup.py file from distutils.

3) Build your documention

> make clean; make html;

Now all your files should be properly documentated by Sphinx.

Upvotes: 4

Related Questions