sphinx documenting: .py file outside of the sphinx root

Question

I need some help with sphinx doc generator My git repo looks like this:

root:

• docs (for sphinx stuff)
• code (for micropython stuff) The thing is that spinx not really able to use files outside of root directory. But no problem (I thought, after digging around in deepest stackoverflow topics) I created a boot_link.rst file what looks like the following. (I needed to add a title, otherwise it wont be generated.)

.. include:: ../../repo/boot.py

Boot file
==========

and my toctree in index.rst looks like this:

.. toctree::
   :maxdepth: 2
   :caption: source code:
   
   Boot file <boot_link.rst>

And now Spinx can read my boot.py file, but it is a total mess. The boot page looks like the follow:

• First the source code, as it is(so code is there, and also every comment, basicly every caracter from the .py file, just dumped there)
• then the boot file title at the end. :D Can I get some help how to fix it? The end result should be a nice formatted page based on the comments of boot.py file. (And the rest of the files from my repo also later, for )

Answer 1

EDIT: Okay, I found the solution. add this to index.rst:

.. toctree::
   :maxdepth: 2
   :caption: source code:
   
   autodoc

add this to conf.py

import os
import sys

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

and also this:

extensions = ['sphinx.ext.autodoc']

and finally create autodoc.rst like this:

.. _autodoc:
 
.. contents::
 
something.py
=================
 
.. automodule:: something
  :members:
  :undoc-members:
  
  
something1.py
=================
 
.. automodule:: something1
  :members:
  :undoc-members:
  
  
something2.py
=================
 
.. automodule:: something2
  :members:
  :undoc-members:

I think that is it.