0

I am using Sphinx to generate documentation from docstrings.

Here is a simple function I have written with some docstring:

# myproject/src/foo.py

def my_func(arg1: int, arg2: int, arg3: str = "some_text") -> tuple[str, str, str]:
    """summary
    
    extended_summary
    
    :param int arg1: description
    :param int arg2: description
    :param str, optional arg3: description, defaults to "some_text"
    
    :return: [description]
    :rtype: tuple[str, str, str]
    """
    
    a, b, c = str(arg1), str(arg2), arg3
 
    return a, b, c

I do sphinx-quickstart in myproject/docs. Then I run sphinx-apidoc --force -o ./docs/_modules ./src and then change directory to docs and run make html

And this is some of my conf.py

sys.path.insert(
    0, os.path.join(os.path.abspath(os.path.dirname(os.path.dirname(__file__))), "src")
)
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.viewcode",
    "sphinx.ext.intersphinx",
    "sphinx.ext.autosummary",
]

autodoc_member_order = "bysource"

autodoc_default_options = {
    "members": True,
    "show-inheritance": True,
}
autosummary_generate = True

This generates:

enter image description here

But when I click on [Source], it is not showing the code. What is the problem?

As this is part of a big project, there are some warnings

Running Sphinx v4.4.0
.
.
.
* ModuleNotFoundError: No module named 'src'
.
.
.
WARNING: autodoc: failed to import module '....' from module '....'; the following exception was raised:
No module named 'src'
WARNING: autodoc: failed to import module '....' from module '....'; the following exception was raised:
No module named 'src'

WARNING: autodoc: failed to import module '.....' from module '....'; the following exception was raised:
No module named 'src'
looking for now-outdated files... none found
pickling environment... done
checking consistency... C:...\docs\_modules\modules.rst: **WARNING**: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] index
generating indices... genindex py-modindex done
highlighting module code... [100%] xml_reader.xml_reader
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 4 warnings.

The HTML pages are in _build\html.

This is the project structure:

myproject
   docs
       conf.py
   src
       foo.py
       package_1
            bar.py
            __init__.py
   venv

What I have tried: I moved foo.py to the package_1 directory. If there, it is working. But in src, not working even though I have added init.py to src

Amin Ba
  • 1,603
  • 1
  • 13
  • 38
  • Strange. Are there any warning/error messages when you run "make html"? What version of Sphinx do you use? Does nothing at all happen when you click the link? – mzjn Jan 21 '22 at 18:42
  • Edited the question – Amin Ba Jan 21 '22 at 18:50
  • Maybe, because of this: https://github.com/readthedocs/readthedocs.org/issues/2139#issuecomment-352205428 – Amin Ba Jan 21 '22 at 18:57
  • 1
    Yes, that looks similar to many older SO questions. For example: https://stackoverflow.com/q/57763542/407651, https://stackoverflow.com/q/50230797/407651, https://stackoverflow.com/q/41925973/407651. – mzjn Jan 21 '22 at 18:59

1 Answers1

1

This solved the problem

Changed

sys.path.insert(
    0, os.path.join(os.path.abspath(os.path.dirname(os.path.dirname(__file__))), "src")
)

to

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

and added __init__.py to ./src/

myproject
   docs
       conf.py
   src
       __init__.py
       foo.py
       package_1
            bar.py
            __init__.py
   venv
Yogev Neumann
  • 2,099
  • 2
  • 13
  • 24
Amin Ba
  • 1,603
  • 1
  • 13
  • 38