Move module docs into module docstrings

inducer · Feb 5, 2025 · e1b93cc · e1b93cc
1 parent ac8b3ba
commit e1b93cc
Show file tree

Hide file tree

Showing 6 changed files with 51 additions and 49 deletions.
diff --git a/codepy/__init__.py b/codepy/__init__.py
@@ -1,2 +1,14 @@
+"""
+Errors
+^^^^^^
+
+.. autoexception:: CompileError
+
+.. automodule:: codepy.jit
+.. automodule:: codepy.toolchain
+.. automodule:: codepy.bpl
+"""
+
+
 class CompileError(Exception):
     pass
diff --git a/codepy/bpl.py b/codepy/bpl.py
@@ -1,4 +1,11 @@
-"""Convenience interface for using CodePy with Boost.Python."""
+"""
+:mod:`codepy.bpl` -- Support for Boost.Python
+---------------------------------------------
+
+.. autoclass:: BoostPythonModule
+    :members:
+    :undoc-members:
+"""
 
 from collections.abc import Callable, Iterable
 from dataclasses import replace

diff --git a/codepy/jit.py b/codepy/jit.py
@@ -1,4 +1,10 @@
-"""Just-in-time Python extension compilation."""
+"""
+:mod:`codepy.jit` -- Compilation and Linking of C Source Code
+-------------------------------------------------------------
+
+.. autofunction:: extension_file_from_string
+.. autofunction:: extension_from_string
+"""
 
 
 __copyright__ = """
@@ -56,7 +62,7 @@ def extension_file_from_string(
         debug: bool = False) -> None:
     """Using *toolchain*, build the extension file named *ext_file*
     from the source code in *source_string*, which is saved to a
-    temporary file named *source_name*. Raise :exc:`CompileError` in
+    temporary file named *source_name*. Raise :exc:`~codepy.CompileError` in
     case of error.
 
     If *debug* is True, show commands involved in the build.
@@ -198,7 +204,7 @@ def extension_from_string(
         sleep_delay: int = 1) -> ModuleType:
     """Return a reference to the extension module *name*, which can be built
     from the source code in *source_string* if necessary. Raise
-    :exc:`CompileError` in case of error.
+    :exc:`codepy.CompileError` in case of error.
 
     Compiled code is cached in *cache_dir* and available immediately if it has
     been compiled at some point in the past. Compiler and Python API versions
@@ -264,7 +270,7 @@ def compile_from_string(
     *recompiled* is *True* if the object had to be recompiled, *False* if the cache
     is hit.
 
-    Raises :exc:`CompileError` in case of error.  The *mod_name* and *file_name*
+    Raises :exc:`~codepy.CompileError` in case of error.  The *mod_name* and *file_name*
     are designed to be used with ``load_dynamic`` to load a Python module from
     this object, if desired.
 

diff --git a/codepy/toolchain.py b/codepy/toolchain.py
@@ -1,4 +1,22 @@
-"""Toolchains for Just-in-time Python extension compilation."""
+"""
+:mod:`codepy.toolchain` -- Tool support code
+--------------------------------------------
+
+.. autoexception:: ToolchainGuessError
+
+.. autoclass:: Toolchain
+    :members: copy, get_version, abi_id, add_library, build_extension
+    :undoc-members:
+
+.. autoclass:: GCCLikeToolchain
+    :show-inheritance:
+
+.. autoclass:: GCCToolchain
+    :show-inheritance:
+
+.. autofunction:: guess_toolchain
+
+"""
 
 __copyright__ = """
 "Copyright (C) 2008,9 Andreas Kloeckner, Bryan Catanzaro
@@ -108,7 +126,7 @@ def build_extension(self,
                         source_files: list[str],
                         debug: bool = False) -> None:
         """Create the extension file *ext_file* from *source_files*
-        by invoking the toolchain. Raise :exc:`~codepy.jit.CompileError` in
+        by invoking the toolchain. Raise :exc:`~codepy.CompileError` in
         case of error.
 
         If *debug* is True, print the commands executed.

diff --git a/doc/index.rst b/doc/index.rst
@@ -5,8 +5,6 @@
 Welcome to CodePy's documentation!
 ==================================
 
-.. module:: codepy
-
 CodePy is a C metaprogramming toolkit for Python. It handles two aspects of
 metaprogramming:
 

diff --git a/doc/jit.rst b/doc/jit.rst
@@ -14,43 +14,4 @@ to determine a few configuration values, notably:
 For lack of better installation documentation at this moment, please see `this
 wiki page <http://wiki.tiker.net/Hedge/HowTo/InstallingFromGit>`_.
 
-:mod:`codepy.jit` -- Compilation and Linking of C Source Code
--------------------------------------------------------------
-
-.. module:: codepy.jit
-
-.. autofunction:: extension_file_from_string
-.. autofunction:: extension_from_string
-
-Errors
-^^^^^^
-
-.. autoexception:: CompileError
-
-:mod:`codepy.toolchain` -- Tool support code
---------------------------------------------
-
-.. module:: codepy.toolchain
-
-.. autoexception:: ToolchainGuessError
-
-.. autoclass:: Toolchain
-    :members: copy, get_version, abi_id, add_library, build_extension
-    :undoc-members:
-
-.. autoclass:: GCCLikeToolchain
-    :show-inheritance:
-
-.. autoclass:: GCCToolchain
-    :show-inheritance:
-
-.. autofunction:: guess_toolchain
-
-:mod:`codepy.bpl` -- Support for Boost.Python
----------------------------------------------
-
-.. automodule:: codepy.bpl
-
-.. autoclass:: BoostPythonModule
-    :members:
-    :undoc-members:
+.. automodule:: codepy