Basic documentation

.gitignore

@@ -5,6 +5,9 @@ build/
 *.egg-info
 *.pyc
 
+#sphinx
+docs/_build/
+
 # IDEs
 **/.idea
 

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 os
-# import sys
+import sys
-# sys.path.insert(0, os.path.abspath('.'))
+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,13 +40,12 @@ 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,

docs/index.rst

@@ -1,15 +1,10 @@
-.. python-rgbcx documentation master file, created by
+Welcome to Quicktex's documentation!
-   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!
 ========================================
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
+   reference/index.rst
 
 
 Indices and tables

docs/reference/index.rst

@@ -1,2 +1,7 @@
-index.rst
+Reference
-============
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   s3tc.rst

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:

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_<IType>(s3tc, "InterpolatorType")
+    auto interpolator_type = py::enum_<IType>(s3tc, "InterpolatorType", R"pbdoc(
-        .value("Ideal", IType::Ideal)
+An enum representing various methods for interpolating colors, used by the BC1 and BC3 encoders/decoders.
-        .value("IdealRound", IType::IdealRound)
+Vendor-specific interpolation modes should only be used when the result will only be used on that type of GPU.
-        .value("Nvidia", IType::Nvidia)
+For most applications, :py:attr:`~quicktex.s3tc.InterpolatorType.Ideal` should be used.
-        .value("AMD", IType::AMD);
+)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);