From d39e0c06f79b30e39e8adef588680134b991e858 Mon Sep 17 00:00:00 2001 From: drewcassidy Date: Mon, 15 Mar 2021 02:49:34 -0700 Subject: [PATCH] Basic documentation --- .gitignore | 3 ++ docs/conf.py | 17 ++++---- docs/index.rst | 9 +---- docs/reference/index.rst | 9 ++++- docs/reference/rgbcx.rst | 0 docs/reference/s3tc.rst | 81 +++++++++++++++++++++++++++++++++++++ quicktex/s3tc/_bindings.cpp | 15 ++++--- 7 files changed, 112 insertions(+), 22 deletions(-) delete mode 100644 docs/reference/rgbcx.rst create mode 100644 docs/reference/s3tc.rst diff --git a/.gitignore b/.gitignore index 544a83d..6f9361b 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,9 @@ build/ *.egg-info *.pyc +#sphinx +docs/_build/ + # IDEs **/.idea diff --git a/docs/conf.py b/docs/conf.py index 0a6cec6..7141662 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,24 +10,26 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +import os +import sys +sys.path.insert(0, os.path.abspath('../quicktex')) # -- Project information ----------------------------------------------------- -project = 'python-rgbcx' +project = 'Quicktex' copyright = '2021, Andrew Cassidy' author = 'Andrew Cassidy' - # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'myst_parser', + 'sphinx_rtd_theme', + 'sphinx.ext.autodoc' ] # Add any paths that contain templates here, relative to this directory. @@ -38,15 +40,14 @@ templates_path = ['_templates'] # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] \ No newline at end of file +html_static_path = ['_static'] diff --git a/docs/index.rst b/docs/index.rst index 43b6d74..d476089 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,15 +1,10 @@ -.. python-rgbcx documentation master file, created by - sphinx-quickstart on Fri Mar 12 17:14:02 2021. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to python-rgbcx's documentation! +Welcome to Quicktex's documentation! ======================================== .. toctree:: :maxdepth: 2 - :caption: Contents: + reference/index.rst Indices and tables diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 638d815..178bdaf 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -1,2 +1,7 @@ -index.rst -============ \ No newline at end of file +Reference +========= + +.. toctree:: + :maxdepth: 2 + + s3tc.rst \ No newline at end of file diff --git a/docs/reference/rgbcx.rst b/docs/reference/rgbcx.rst deleted file mode 100644 index e69de29..0000000 diff --git a/docs/reference/s3tc.rst b/docs/reference/s3tc.rst new file mode 100644 index 0000000..9cb5898 --- /dev/null +++ b/docs/reference/s3tc.rst @@ -0,0 +1,81 @@ +.. py:currentmodule:: quicktex.s3tc + +s3tc module +=========== + +.. pybind handles enums in a really weird way that doesnt play nice with Sphinx, + so the docs are rewritten here. + +.. py:class:: InterpolatorType + + An enum representing various methods for interpolating colors, used by the BC1 and BC3 encoders/decoders. + Vendor-specific interpolation modes should only be used when the result will only be used on that type of GPU. + For most applications, :py:attr:`~quicktex.s3tc.InterpolatorType.Ideal` should be used. + + .. py:data:: Ideal + + The default mode, with no rounding for colors 2 and 3. This matches the D3D10 docs on BC1. + + .. py:data:: IdealRound + + Round colors 2 and 3. Matches the AMD Compressonator tool and the D3D9 docs on DXT1. + + .. py:data:: Nvidia + + Nvidia GPU mode. + + .. py:data:: AMD + + AMD GPU mode. + +bc1 module +---------- + +.. automodule:: quicktex.s3tc.bc1 + + .. autoclass:: BC1Encoder + :members: + :undoc-members: + + .. autoclass:: BC1Decoder + :members: + :undoc-members: + +bc3 module +---------- + +.. automodule:: quicktex.s3tc.bc3 + + .. autoclass:: BC3Encoder + :members: + :undoc-members: + + .. autoclass:: BC3Decoder + :members: + :undoc-members: + +bc4 module +---------- + +.. automodule:: quicktex.s3tc.bc4 + + .. autoclass:: BC4Encoder + :members: + :undoc-members: + + .. autoclass:: BC4Decoder + :members: + :undoc-members: + +bc5 module +---------- + +.. automodule:: quicktex.s3tc.bc5 + + .. autoclass:: BC5Encoder + :members: + :undoc-members: + + .. autoclass:: BC5Decoder + :members: + :undoc-members: \ No newline at end of file diff --git a/quicktex/s3tc/_bindings.cpp b/quicktex/s3tc/_bindings.cpp index 87bc329..55a8ffa 100644 --- a/quicktex/s3tc/_bindings.cpp +++ b/quicktex/s3tc/_bindings.cpp @@ -36,11 +36,16 @@ void InitS3TC(py::module_ &m) { py::module_ s3tc = m.def_submodule("_s3tc", "s3tc compression library based on rgbcx.h written by Richard Goldreich"); using IType = Interpolator::Type; - py::enum_(s3tc, "InterpolatorType") - .value("Ideal", IType::Ideal) - .value("IdealRound", IType::IdealRound) - .value("Nvidia", IType::Nvidia) - .value("AMD", IType::AMD); + auto interpolator_type = py::enum_(s3tc, "InterpolatorType", R"pbdoc( +An enum representing various methods for interpolating colors, used by the BC1 and BC3 encoders/decoders. +Vendor-specific interpolation modes should only be used when the result will only be used on that type of GPU. +For most applications, :py:attr:`~quicktex.s3tc.InterpolatorType.Ideal` should be used. +)pbdoc"); + + interpolator_type.value("Ideal", IType::Ideal, "The default mode, with no rounding for colors 2 and 3. This matches the D3D10 docs on BC1."); + interpolator_type.value("IdealRound", IType::IdealRound, "Round colors 2 and 3. Matches the AMD Compressonator tool and the D3D9 docs on DXT1."); + interpolator_type.value("Nvidia", IType::Nvidia, "Nvidia GPU mode."); + interpolator_type.value("AMD", IType::AMD, "AMD GPU mode."); InitBC1(s3tc); InitBC3(s3tc);