I am trying to document my project in Odoo with sphinx.

[diogocarreirarxi]

Hello, i am trying to document my project in odoo, i can document modules, but i cant document modules inside folders and subfolders. I read the documentation but didnt find a way to be able to reach the modules inside the folders.

[AA-Turner]

Hi,

There's nothing really to go on here -- please provide a reproducible example of the failure, and what you've already tried, so that people can try and help.

A

[timhoffm]

As a general note, you must make sure that Sphinx can find the modules you want to document. See https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#ensuring-the-code-can-be-imported

[diogocarreirarxi]

here is my example:

Here is the script I created to automatically document and open a browser session (for testing).

#!/bin/bash

# Function to install dependencies
install_dependencies() {
    echo "Installing Sphinx..."
    pip install sphinx
    echo "Installing sphinx-rtd-theme..."
    pip install sphinx-rtd-theme
}

# Function to run sphinx-quickstart inside a sphinx directory
run_sphinx_quickstart() {
    mkdir -p sphinx  # Create sphinx directory if it doesn't exist
    cd sphinx        # Move into sphinx directory
    sphinx-quickstart --quiet --project "Teste" --author "Victor" --release "0.1" --language "pt" --sep --makefile --batchfile --extensions "sphinx.ext.autodoc,sphinx.ext.napoleon,sphinx.ext.viewcode,sphinx.ext.intersphinx,sphinx.ext.autosummary"
}

# Function to delete the current conf.py and recreate it with updated content
recreate_conf_py() {
    sphinx_path=$1  # Path to the user's provided folder

    # Navigate to the source folder where conf.py is generated
    cd source

    # Delete the existing conf.py
    rm -f conf.py

    # Create a new conf.py with the updated content
    echo "
import os
import sys
from pathlib import Path

sys.path.insert(0, os.path.abspath('/home/dev2/odoo/odoo16/odoo-server'))
sys.path.insert(0, os.path.abspath('$sphinx_path'))  # User's provided path goes here
sys.path.insert(0, os.path.abspath('../'))
sys.path.insert(0, str(Path('..', 'src').resolve()))

autodoc_mock_imports = ['odoo', 'odoo.addons']

project = 'Teste'
copyright = '2024, Victor'
author = 'Victor'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
    'sphinx.ext.intersphinx',
    'sphinx.ext.autosummary',
]

viewcode_line_numbers = True
templates_path = ['_templates']
exclude_patterns = ['**/__init__.py', '**/__manifest__.py']

autodoc_default_options = {
    'members': True,
    'undoc-members': True,
    'private-members': True,
    'special-members': '__init__',
    'inherited-members': True,
    'show-inheritance': True
}

language = 'pt'

html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
" > conf.py

    echo "conf.py recreated with the provided path."
}

# Function to add 'modules' entry to index.rst
update_index_rst() {
    cd source

    # Add standard heading and 'modules' to index.rst
    echo ".. Teste documentation master file

Welcome to the Teste documentation!
===================================

.. toctree::
   :maxdepth: 6
   :caption: Contents:

   modules
" > index.rst

    echo "index.rst updated with 'modules' entry."
}

# Function to generate Sphinx documentation files from the provided path
build_sphinx_files() {
    sphinx_path=$1  # Path to the user's provided folder
    cd ..
    cd sphinx
    sphinx-apidoc -f -M -o source/ $sphinx_path
    echo " you are now inside the path: $(pwd)"
    echo " you are now inside the path: $(pwd)"
    echo " you are now inside the path: $(pwd)"
    echo " you are now inside the path: $(pwd)"
    echo " you are now inside the path: $(pwd)"
    echo " you are now inside the path: $(pwd)"

    make clean
    make html

    index_file="build/html/index.html"
    if [[ -f "$index_file" ]]; then
        'google-chrome' "$index_file" &
        echo "Documentation opened in your default browser." &
        echo "Sphinx setup is complete!"
    else
        echo "Index file not found at $index_file. Please check the path."
    fi
}

# Main script execution
read -p "Enter the full path to your Odoo server directory (e.g., /home/dev2/odoo/odoo16/arxi-quality-servers/arxi-quality-client): " server_path

# Print the path with a smiley face
echo "You provided: $server_path :)"

# Install necessary dependencies (Sphinx and sphinx-rtd-theme)
install_dependencies

# Create sphinx folder and run sphinx-quickstart
run_sphinx_quickstart

# Delete and recreate conf.py with the server path provided by the user
recreate_conf_py "$server_path"

# Update index.rst to include 'modules'
update_index_rst

# Generate Sphinx documentation files for the provided server path
build_sphinx_files "$server_path"

# Go back to the original folder (parent directory)
cd ../..

echo "Sphinx setup is complete!"

My problem is that I cannot make the script acknowledge subfolders, only folders it considers a "module", which I believe reads as folders with __init__.py inside of them.

Is there a way for me to document every python module, even if it is not in an upper level folder? Here is an example:

what i tried:
Using arguments f, m, o in sphinx script
Manually changing :maxdepth: on toctree to multiple values
Adding __init__.py files to multiple subfolders (not ideal)

thank u for the help!

[AA-Turner]

We're still missing some context. Is the following correct?

├─conf.py
├─index.rst
├─server-models-dir/
| ├─package-first-level/
│ └─subfolder/
│   ├─package-a/
|   ├─package-b/
|   ├─package-c/

If so, currently only package-first-level is documented?

You're using sphinx-apidoc with sphinx-apidoc --force --module-first -o source/.

I would suggest trying --implicit-namespaces, but this might not work as your project has an odd structure -- given the name of the folder in the supplied image, it doesn't seem like you intend to use namespace packages.

A

[diogocarreirarxi]

its like this for example:

with this in conf.py:
sys.path.insert(0, os.path.abspath('/home/dev2/odoo/odoo16/odoo-server')) sys.path.insert(0, os.path.abspath('$sphinx_path')) # User's provided path goes here sys.path.insert(0, os.path.abspath('../')) sys.path.insert(0, str(Path('..', 'src').resolve()))
package-first-level is documented

but if the package is inside a sub folder like in the example:

subfolder/package-a:

its not documented

[AA-Turner]

Several of the directories in the conf.py don't appear in your tree.

What is the import path of these packages? The parent folders use hyphens, so they're not valid names in Python.

[diogocarreirarxi]

sys.path.insert(0, os.path.abspath('/home/dev2/odoo/odoo16/odoo-server'))

• this path is because the packages i am trying to document have dependencies from odoo-server, and at least has being working with the hyphen.

sys.path.insert(0, os.path.abspath('$sphinx_path'))

• this is the path for the project with packages that i want to document in this case "server-models-dir".

sys.path.insert(0, os.path.abspath('../')) sys.path.insert(0, str(Path('..', 'src').resolve()))
-these 2 has trial and error until it worked, it worked to document the first depth level package in this case "package-first-level".

the problem is i cant document the second depth level package: the package-a inside subfolder: subfolder/package-a

full tree view:

thank u for the help!