From e1b93cc0bf28e69afd684b4a933555d324645bb3 Mon Sep 17 00:00:00 2001 From: Andreas Kloeckner Date: Wed, 5 Feb 2025 12:54:54 -0600 Subject: [PATCH] Move module docs into module docstrings --- codepy/__init__.py | 12 ++++++++++++ codepy/bpl.py | 9 ++++++++- codepy/jit.py | 14 ++++++++++---- codepy/toolchain.py | 22 ++++++++++++++++++++-- doc/index.rst | 2 -- doc/jit.rst | 41 +---------------------------------------- 6 files changed, 51 insertions(+), 49 deletions(-) diff --git a/codepy/__init__.py b/codepy/__init__.py index 1cd9d88..d99a663 100644 --- 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 index f6f7455..4c3c4d6 100644 --- 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 index 45118a7..8aea1af 100644 --- 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 index c11370a..29aafb3 100644 --- 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 index 1c522cc..8c398ce 100644 --- 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 index 2de0f85..053d5a9 100644 --- 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 `_. -: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