Sphinx Documentation Generator

import os
import shutil
from sphinx.application import Sphinx
from sphinx.util.docutils import docutils_namespace

# Define paths
source_dir = "docs_src"
build_dir = os.path.join(source_dir, "_build")
output_html_dir = os.path.join(build_dir, "html")
doctrees_dir = os.path.join(build_dir, ".doctrees")

# Clean up previous build if exists
if os.path.exists(source_dir):
    shutil.rmtree(source_dir)

# Create source directories
os.makedirs(source_dir)
os.makedirs(os.path.join(source_dir, "_static"))
os.makedirs(os.path.join(source_dir, "_templates"))

# Create a simple Python module to document
module_path = os.path.join(source_dir, "my_module.py")
with open(module_path, "w") as f:
    f.write("""
def greet(name: str) -> str:
    """Greets the given name.

    :param name: The name to greet.
    :type name: str
    :returns: A greeting string.
    :rtype: str
    """
    return f"Hello, {name}!"

class Greeter:
    """A simple greeter class.

    :param greeting_word: The word to use for greeting.
    :type greeting_word: str
    """
    def __init__(self, greeting_word: str = "Hello"):
        self.greeting_word = greeting_word

    def wave(self, name: str) -> str:
        """Waves to the given name.

        :param name: The name to wave to.
        :type name: str
        :returns: A waving greeting.
        :rtype: str
        """
        return f"{self.greeting_word}, {name}! *waves*"
""")

# Create conf.py
conf_path = os.path.join(source_dir, "conf.py")
with open(conf_path, "w") as f:
    f.write("""
import os
import sys
sys.path.insert(0, os.path.abspath('.'))

project = 'My Sphinx Project'
copyright = '2026, My Name'
author = 'My Name'
release = '0.1'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon', # for Google/NumPy style docstrings
]

html_theme = 'alabaster'
""")

# Create index.rst
index_path = os.path.join(source_dir, "index.rst")
with open(index_path, "w") as f:
    f.write("""
.. _index:

Welcome to My Sphinx Project!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules

This is a sample project to demonstrate Sphinx documentation.
""")

# Create modules.rst for autodoc
modules_path = os.path.join(source_dir, "modules.rst")
with open(modules_path, "w") as f:
    f.write("""
Module Documentation
====================

.. automodule:: my_module
   :members:
   :undoc-members:
   :show-inheritance:
""")

try:
    # Initialize and build the Sphinx application
    # Use docutils_namespace to ensure clean Docutils state
    with docutils_namespace():
        app = Sphinx(
            sourcedir=source_dir,
            confdir=source_dir,
            outdir=output_html_dir,
            doctreedir=doctrees_dir,
            buildername="html",
            freshenv=True,  # Re-read all files
            warningiserror=False,
            # status=sys.stdout, # Uncomment to see build status in console
            # warning=sys.stderr, # Uncomment to see warnings in console
        )
        app.build(force_all=True)
    print(f"Documentation built successfully in {output_html_dir}")
    print(f"Open file://{os.path.abspath(output_html_dir)}/index.html in your browser.")
except Exception as e:
    print(f"Error building documentation: {e}")
    import traceback
    traceback.print_exc()
finally:
    # Optional: Clean up created files and directories
    # if os.path.exists(source_dir):
    #     shutil.rmtree(source_dir)
    pass