Include python files in book

[JoopBanaan]

My code consists of Jupyter notebooks and libraries in python.
I would love to include the docstrings of the python files into the Jupyter book. Is that possible?

[chrisjsewell]

Heya, indeed it is very possible, using https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html.
There is lots of example of this in the EBP repositories (directly using sphinx but this is also applicable to jupyterbook). Maybe look at e.g. https://github.com/executablebooks/MyST-Parser/blob/master/docs/api/reference.rst

and note also: https://myst-parser.readthedocs.io/en/latest/sphinx/use.html#use-sphinx-ext-autodoc-in-markdown-files

[JoopBanaan]

My 1st hurdle: include the python file in the _toc.yml, is not successful: toctree contains reference to nonexisting document 'test_docstring'
I double checked the existence of the file test_docstring.py in the same directory.
BTW I also tried
- file: test_docstring.py
# including extension ".py"

[chrisjsewell]

you shouldn't include the actual python file in the toc, just reference it either via autodoc, or using a https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude

[JoopBanaan]

How to append sys.path so that the module is found?
Currently I use in _config.yml:

sphinx:
  local_extensions:
    test_docstring: /<path to folder where module resides in>/

which works but is not the intended use of local extensions

[JoopBanaan]

To answer this question for my future self (and maybe others):
In an *.md file add:

.. automodule:: test_docstring
    :members: 
assuming you write docstrings in this format:

def testing(joop):
    """mooie func
    Args:
        joop ([type]): [description]
    Returns:
        [type]: [description]

to extend the sys.path so that module can be loaded
create a file : dummy_extension.py in the folder of the module

def setup(bs):
	    pass

add to _config.yml:

sphinx:
	  config:
		# fake an extension to get folder added to sys.path
		  local_extensions:
		    dummy_extension: /<path to module folder>

and don't forget to update to version 0.11.1

jupyter-book --version:

Jupyter Book : 0.11.1
External ToC : 0.2.2
MyST-Parser : 0.13.7
MyST-NB : 0.12.3
Sphinx Book Theme : 0.1.0
Jupyter-Cache : 0.4.2
NbClient : 0.5.1

Thanks Chris for the pointers

[cal-and-bist]

correction: docstring must be in reST format: