From f7821c3a70f32faf7192e37c23f2d57b948adcfc Mon Sep 17 00:00:00 2001 From: drewcassidy Date: Sun, 21 Mar 2021 20:36:26 -0700 Subject: [PATCH] Document base classes --- docs/conf.py | 5 ++-- docs/reference/formats/s3tc.rst | 21 ++++++-------- quicktex/s3tc/bc1/_bindings.cpp | 12 ++++++-- quicktex/s3tc/bc3/_bindings.cpp | 12 ++++++-- quicktex/s3tc/bc4/_bindings.cpp | 12 ++++++-- quicktex/s3tc/bc5/_bindings.cpp | 12 ++++++-- quicktex/s3tc/interpolator/_bindings.cpp | 35 ++++++++++++++++++------ 7 files changed, 77 insertions(+), 32 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index d076004..e43bdc8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -59,8 +59,9 @@ add_module_names = False autodoc_docstring_signature = True autodoc_default_options = { - 'member-order': 'groupwise', - 'exclude-members': '__weakref__' + 'member-order': 'bysource', + 'exclude-members': '__weakref__', + 'imported-members': True, } # -- Options for Intersphinx ------------------------------------------------ diff --git a/docs/reference/formats/s3tc.rst b/docs/reference/formats/s3tc.rst index 418b1fc..5b87d42 100644 --- a/docs/reference/formats/s3tc.rst +++ b/docs/reference/formats/s3tc.rst @@ -7,7 +7,7 @@ bc1 module ---------- .. automodule:: quicktex.s3tc.bc1 - .. autoclass:: BC1Encoder(BlockEncoder) + .. autoclass:: BC1Encoder .. automethod:: __init__ .. automethod:: set_level @@ -38,7 +38,7 @@ bc1 module .. autoclass:: quicktex.s3tc.bc1::BC1Encoder.EndpointMode .. autoclass:: quicktex.s3tc.bc1::BC1Encoder.ErrorMode - .. autoclass:: BC1Decoder(BlockDecoder) + .. autoclass:: BC1Decoder .. automethod:: __init__ .. autoproperty:: interpolator(self) -> quicktex.s3tc.interpolator.Interpolator @@ -48,13 +48,13 @@ bc3 module ---------- .. automodule:: quicktex.s3tc.bc3 - .. autoclass:: BC3Encoder(BlockEncoder) + .. autoclass:: BC3Encoder .. automethod:: __init__ .. autoproperty:: bc1_encoder(self) -> quicktex.s3tc.bc1.BC1Encoder .. autoproperty:: bc4_encoder(self) -> quicktex.s3tc.bc4.BC4Encoder - .. autoclass:: BC3Decoder(BlockDecoder) + .. autoclass:: BC3Decoder .. automethod:: __init__ .. autoproperty:: bc1_decoder(self) -> quicktex.s3tc.bc1.BC1Decoder @@ -64,12 +64,12 @@ bc4 module ---------- .. automodule:: quicktex.s3tc.bc4 - .. autoclass:: BC4Encoder(BlockEncoder) + .. autoclass:: BC4Encoder .. automethod:: __init__ .. autoproperty:: channel(self) -> int - .. autoclass:: BC4Decoder(BlockDecoder) + .. autoclass:: BC4Decoder .. automethod:: __init__ .. autoproperty:: channel(self) -> int @@ -78,13 +78,13 @@ bc5 module ---------- .. automodule:: quicktex.s3tc.bc5 - .. autoclass:: BC5Encoder(BlockEncoder) + .. autoclass:: BC5Encoder .. automethod:: __init__ .. autoproperty:: bc4_encoders(self) -> tuple[quicktex.s3tc.bc4.BC4Encoder] .. autoproperty:: channels(self) -> tuple[int, int] - .. autoclass:: BC5Decoder(BlockDecoder) + .. autoclass:: BC5Decoder .. automethod:: __init__ .. autoproperty:: bc4_decoders(self) -> tuple[quicktex.s3tc.bc4.BC4Decoder] @@ -95,8 +95,3 @@ interpolator module .. automodule:: quicktex.s3tc.interpolator :members: - - .. autoclass:: Interpolator - .. autoclass:: InterpolatorRound(Interpolator) - .. autoclass:: InterpolatorNvidia(Interpolator) - .. autoclass:: InterpolatorAMD(Interpolator) diff --git a/quicktex/s3tc/bc1/_bindings.cpp b/quicktex/s3tc/bc1/_bindings.cpp index 9d660d4..01a75de 100644 --- a/quicktex/s3tc/bc1/_bindings.cpp +++ b/quicktex/s3tc/bc1/_bindings.cpp @@ -48,7 +48,11 @@ void InitBC1(py::module_ &s3tc) { options.disable_function_signatures(); // BC1Encoder - py::class_ bc1_encoder(bc1, "BC1Encoder", block_encoder, "Encodes RGB textures to BC1"); + py::class_ bc1_encoder(bc1, "BC1Encoder", block_encoder, R"doc( + Base: :py:class:`~quicktex.BlockEncoder` + + Encodes RGB textures to BC1. + )doc"); py::enum_(bc1_encoder, "EndpointMode", "Enum representing various methods of finding endpoints in a block.") .value("LeastSquares", BC1Encoder::EndpointMode::LeastSquares, "Find endpoints using a 2D least squares approach.") @@ -129,7 +133,11 @@ void InitBC1(py::module_ &s3tc) { "Automatically clamped to between :py:const:`BC1Encoder.min_power_iterations` and :py:const:`BC1Encoder.max_power_iterations`"); // BC1Decoder - py::class_ bc1_decoder(bc1, "BC1Decoder", block_decoder, "Decodes BC1 textures to RGB"); + py::class_ bc1_decoder(bc1, "BC1Decoder", block_decoder, R"doc( + Base: :py:class:`~quicktex.BlockDecoder` + + Decodes BC1 textures to RGB + )doc"); bc1_decoder.def(py::init(), "write_alpha"_a = false); bc1_decoder.def(py::init(), "write_alpha"_a, "interpolator"_a, R"pbdoc( diff --git a/quicktex/s3tc/bc3/_bindings.cpp b/quicktex/s3tc/bc3/_bindings.cpp index 1083cef..36833df 100644 --- a/quicktex/s3tc/bc3/_bindings.cpp +++ b/quicktex/s3tc/bc3/_bindings.cpp @@ -48,7 +48,11 @@ void InitBC3(py::module_ &s3tc) { options.disable_function_signatures(); // BC3Encoder - py::class_ bc3_encoder(bc3, "BC3Encoder", block_encoder, "Encodes RGBA textures to BC3"); + py::class_ bc3_encoder(bc3, "BC3Encoder", block_encoder,R"doc( + Base: :py:class:`~quicktex.BlockEncoder` + + Encodes RGBA textures to BC3 + )doc"); bc3_encoder.def(py::init(), "level"_a = 5); bc3_encoder.def(py::init(), "level"_a, "interpolator"_a, R"doc( @@ -67,7 +71,11 @@ void InitBC3(py::module_ &s3tc) { "Internal :py:class:`~quicktex.s3tc.bc4.BC4Encoder` used for alpha data. Readonly."); // BC3Decoder - py::class_ bc3_decoder(bc3, "BC3Decoder", block_decoder, "Decodes BC3 textures to RGBA"); + py::class_ bc3_decoder(bc3, "BC3Decoder", block_decoder, R"doc( + Base: :py:class:`~quicktex.BlockDecoder` + + Decodes BC3 textures to RGBA + )doc"); bc3_decoder.def(py::init<>()); bc3_decoder.def(py::init(), "interpolator"_a, R"doc( diff --git a/quicktex/s3tc/bc4/_bindings.cpp b/quicktex/s3tc/bc4/_bindings.cpp index a521b74..997b194 100644 --- a/quicktex/s3tc/bc4/_bindings.cpp +++ b/quicktex/s3tc/bc4/_bindings.cpp @@ -44,7 +44,11 @@ void InitBC4(py::module_ &s3tc) { options.disable_function_signatures(); // BC4Encoder - py::class_ bc4_encoder(bc4, "BC4Encoder", block_encoder, "Encodes single-channel textures to BC4."); + py::class_ bc4_encoder(bc4, "BC4Encoder", block_encoder, R"doc( + Base: :py:class:`~quicktex.BlockEncoder` + + Encodes single-channel textures to BC4. + )doc"); bc4_encoder.def(py::init(), py::arg("channel") = 3, R"doc( __init__(channel : int = 3) -> None @@ -56,7 +60,11 @@ void InitBC4(py::module_ &s3tc) { bc4_encoder.def_property_readonly("channel", &BC4Encoder::GetChannel, "The channel that will be read from. 0 to 3 inclusive. Readonly."); // BC4Decoder - py::class_ bc4_decoder(bc4, "BC4Decoder", block_decoder, "Encodes BC4 textures to a single-channel texture."); + py::class_ bc4_decoder(bc4, "BC4Decoder", block_decoder, R"doc( + Base: :py:class:`~quicktex.BlockDecoder` + + Decodes BC4 textures to a single-channel. + )doc"); bc4_decoder.def(py::init(), py::arg("channel") = 3, R"doc( __init__(channel : int = 3) -> None diff --git a/quicktex/s3tc/bc5/_bindings.cpp b/quicktex/s3tc/bc5/_bindings.cpp index c90e2f5..62ba017 100644 --- a/quicktex/s3tc/bc5/_bindings.cpp +++ b/quicktex/s3tc/bc5/_bindings.cpp @@ -41,7 +41,11 @@ void InitBC5(py::module_ &s3tc) { options.disable_function_signatures(); // BC5Encoder - py::class_ bc5_encoder(bc5, "BC5Encoder", block_encoder, "Encodes dual-channel textures to BC5."); + py::class_ bc5_encoder(bc5, "BC5Encoder", block_encoder, R"doc( + Base: :py:class:`~quicktex.BlockEncoder` + + Encodes dual-channel textures to BC5. + )doc"); bc5_encoder.def(py::init(), py::arg("chan0") = 0, py::arg("chan1") = 1, R"doc( __init__(chan0 : int = 0, chan1 : int = 1) -> None @@ -57,7 +61,11 @@ void InitBC5(py::module_ &s3tc) { "2-tuple of internal :py:class:`~quicktex.s3tc.bc4.BC4Encoder` s used for each channel. Readonly."); // BC5Decoder - py::class_ bc5_decoder(bc5, "BC5Decoder", block_decoder, "Decodes BC5 textures to a dual-channel texture."); + py::class_ bc5_decoder(bc5, "BC5Decoder", block_decoder, R"doc( + Base: :py:class:`~quicktex.BlockDecoder` + + Decodes BC4 textures to two channels. + )doc"); bc5_decoder.def(py::init(), py::arg("chan0") = 0, py::arg("chan1") = 1, R"doc( __init__(chan0 : int = 0, chan1 : int = 1) -> None diff --git a/quicktex/s3tc/interpolator/_bindings.cpp b/quicktex/s3tc/interpolator/_bindings.cpp index 4137d95..bed13a7 100644 --- a/quicktex/s3tc/interpolator/_bindings.cpp +++ b/quicktex/s3tc/interpolator/_bindings.cpp @@ -1,7 +1,6 @@ /* Python-rgbcx Texture Compression Library Copyright (C) 2021 Andrew Cassidy - Partially derived from rgbcx.h written by Richard Geldreich - and licenced under the public domain + Partially derived from rgbcx.h written by Richard Geldreich and licenced under the public domain This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by @@ -31,21 +30,39 @@ using namespace quicktex::s3tc; using InterpolatorPtr = std::shared_ptr; void InitInterpolator(py::module_ &s3tc) { - auto interpolator = s3tc.def_submodule("_interpolator", "Internal interpolator module"); + auto interpolator = s3tc.def_submodule("_interpolator", "internal interpolator module"); // Interpolator py::class_ ideal( - interpolator, "Interpolator", - "Interpolator base class representing the default mode, with no rounding for colors 2 and 3. This matches the D3D10 docs on BC1."); + interpolator, "Interpolator", R"doc( + Interpolator base class representing the ideal interpolation mode, with no rounding for colors 2 and 3. + This matches the `D3D10 docs`_ on BC1. + + .. _D3D10 docs: https://docs.microsoft.com/en-us/windows/win32/direct3d10/d3d10-graphics-programming-guide-resources-block-compression + )doc"); // InterpolatorRound - py::class_ round(interpolator, "InterpolatorRound", ideal, - "Round colors 2 and 3. Matches the AMD Compressonator tool and the D3D9 docs on DXT1."); + py::class_ round(interpolator, "InterpolatorRound", ideal, R"doc( + Base: :py:class:`~quicktex.s3tc.interpolator.Interpolator` + + Interpolator class representing the ideal rounding interpolation mode. + Round colors 2 and 3. Matches the AMD Compressonator tool and the `D3D9 docs`_ on DXT1. + + .. _D3D9 docs: https://docs.microsoft.com/en-us/windows/win32/direct3d9/opaque-and-1-bit-alpha-textures + )doc"); // InterpolatorNvidia - py::class_ nvidia(interpolator, "InterpolatorNvidia", ideal, "Nvidia GPU mode."); + py::class_ nvidia(interpolator, "InterpolatorNvidia", ideal, R"doc( + Base: :py:class:`~quicktex.s3tc.interpolator.Interpolator` + + Interpolator class representing the Nvidia GPU interpolation mode. + )doc"); // InterpolatorAMD - py::class_ amd(interpolator, "InterpolatorAMD", ideal, "AMD GPU mode."); + py::class_ amd(interpolator, "InterpolatorAMD", ideal, R"doc( + Base: :py:class:`~quicktex.s3tc.interpolator.Interpolator` + + Interpolator class representing the AMD GPU interpolation mode. + )doc"); } } // namespace quicktex::bindings \ No newline at end of file