Использование Sphinx для документирования модулей ORM Python (Odoo), но не тогда, когда они вложены в подпапки. ⇐ Python

[Anonymous]

все
Я пробовал использовать Sphinx для документирования модулей Python, и пока он работает хорошо. Вот скрипт, который я создал для автоматического документирования и открытия сеанса браузера (для тестирования).

Код: Выделить всё

#!/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!"

Моя проблема в том, что я не могу заставить сценарий распознавать подпапки, а только те папки, которые он содержит «модуль», которые, как мне кажется, читаются как папки с помощью init .py внутри них.
Есть ли способ документировать каждый модуль Python, даже если он сейчас находится в папке верхнего уровня? Вот пример (изображение):
введите сюда описание изображения
Спасибо!

• Использование аргументов f, m, o в скрипте sphinx
• Изменение :maxlength: в toctree на несколько значений вручную
• Добавление файлов __init__.py в несколько подпапок (не идеально)

Подробнее здесь: https://stackoverflow.com/questions/791 ... are-nested