Improving docs: showing name as cppcolormap instead of cppcolormap._cppcolormap

tdegeus · tdegeus · commit 3262f99a9d12 · 2022-02-18T16:54:03.000+01:00
diff --git a/docs/api_python.rst b/docs/api_python.rst
@@ -2,7 +2,236 @@
 Python API
 **********
 
-.. automodule:: cppcolormap._cppcolormap
+Overview
+========
+
+Functions
+---------
+
+.. autosummary::
+
+    cppcolormap.colormap
+    cppcolormap.colorcycle
+    cppcolormap.hex2rgb
+    cppcolormap.rgb2hex
+    cppcolormap.as_colors
+    cppcolormap.match
+    cppcolormap.version
+    cppcolormap.version_dependencies
+
+Colorbrewer
+-----------
+
+.. autosummary::
+
+    cppcolormap.Accent
+    cppcolormap.Dark2
+    cppcolormap.Paired
+    cppcolormap.Spectral
+    cppcolormap.Pastel1
+    cppcolormap.Pastel2
+    cppcolormap.Set1
+    cppcolormap.Set2
+    cppcolormap.Set3
+    cppcolormap.Blues
+    cppcolormap.Greens
+    cppcolormap.Greys
+    cppcolormap.Oranges
+    cppcolormap.Purples
+    cppcolormap.Reds
+    cppcolormap.BuPu
+    cppcolormap.GnBu
+    cppcolormap.PuBu
+    cppcolormap.PuBuGn
+    cppcolormap.PuRd
+    cppcolormap.RdPu
+    cppcolormap.OrRd
+    cppcolormap.RdOrYl
+    cppcolormap.YlGn
+    cppcolormap.YlGnBu
+    cppcolormap.YlOrRd
+    cppcolormap.BrBG
+    cppcolormap.PuOr
+    cppcolormap.RdBu
+    cppcolormap.RdGy
+    cppcolormap.RdYlBu
+    cppcolormap.RdYlGn
+    cppcolormap.PiYG
+    cppcolormap.PRGn
+
+Matplotlib
+----------
+
+.. autosummary::
+
+    cppcolormap.spring
+    cppcolormap.summer
+    cppcolormap.autumn
+    cppcolormap.winter
+    cppcolormap.bone
+    cppcolormap.cool
+    cppcolormap.hot
+    cppcolormap.copper
+    cppcolormap.hsv
+    cppcolormap.nipy_spectral
+    cppcolormap.terrain
+    cppcolormap.seismic
+    cppcolormap.afmhot
+    cppcolormap.magma
+    cppcolormap.inferno
+    cppcolormap.plasma
+    cppcolormap.viridis
+    cppcolormap.jet
+
+Miscelleneous
+-------------
+
+.. autosummary::
+
+    cppcolormap.xterm
+    cppcolormap.tue
+
+Colors
+------
+
+.. autosummary::
+
+    cppcolormap.Apricot
+    cppcolormap.Aquamarine
+    cppcolormap.Bittersweet
+    cppcolormap.Black
+    cppcolormap.Blue
+    cppcolormap.BlueGreen
+    cppcolormap.BlueViolet
+    cppcolormap.BrickRed
+    cppcolormap.Brown
+    cppcolormap.BurntOrange
+    cppcolormap.CadetBlue
+    cppcolormap.CarnationPink
+    cppcolormap.Cerulean
+    cppcolormap.CornflowerBlue
+    cppcolormap.Cyan
+    cppcolormap.Dandelion
+    cppcolormap.DarkOrchid
+    cppcolormap.Emerald
+    cppcolormap.ForestGreen
+    cppcolormap.Fuchsia
+    cppcolormap.Goldenrod
+    cppcolormap.Gray
+    cppcolormap.Green
+    cppcolormap.GreenYellow
+    cppcolormap.Grey
+    cppcolormap.JungleGreen
+    cppcolormap.Lavender
+    cppcolormap.LimeGreen
+    cppcolormap.Magenta
+    cppcolormap.Mahogany
+    cppcolormap.Maroon
+    cppcolormap.Melon
+    cppcolormap.MidnightBlue
+    cppcolormap.Mulberry
+    cppcolormap.NavyBlue
+    cppcolormap.OliveGreen
+    cppcolormap.Orange
+    cppcolormap.OrangeRed
+    cppcolormap.Orchid
+    cppcolormap.Peach
+    cppcolormap.Periwinkle
+    cppcolormap.PineGreen
+    cppcolormap.Plum
+    cppcolormap.ProcessBlue
+    cppcolormap.Purple
+    cppcolormap.RawSienna
+    cppcolormap.Red
+    cppcolormap.RedOrange
+    cppcolormap.RedViolet
+    cppcolormap.Rhodamine
+    cppcolormap.RoyalBlue
+    cppcolormap.RoyalPurple
+    cppcolormap.RubineRed
+    cppcolormap.Salmon
+    cppcolormap.SeaGreen
+    cppcolormap.Sepia
+    cppcolormap.SkyBlue
+    cppcolormap.SpringGreen
+    cppcolormap.Tan
+    cppcolormap.TealBlue
+    cppcolormap.Thistle
+    cppcolormap.tueblue
+    cppcolormap.tuedarkblue
+    cppcolormap.tuelightblue
+    cppcolormap.tuewarmred
+    cppcolormap.Turquoise
+    cppcolormap.Violet
+    cppcolormap.VioletRed
+    cppcolormap.White
+    cppcolormap.WildStrawberry
+    cppcolormap.Yellow
+    cppcolormap.YellowGreen
+    cppcolormap.YellowOrange
+
+Reversed color(map)s
+---------------------
+
+    cppcolormap.Accent_r
+    cppcolormap.Dark2_r
+    cppcolormap.Paired_r
+    cppcolormap.Spectral_r
+    cppcolormap.Pastel1_r
+    cppcolormap.Pastel2_r
+    cppcolormap.Set1_r
+    cppcolormap.Set2_r
+    cppcolormap.Set3_r
+    cppcolormap.Blues_r
+    cppcolormap.Greens_r
+    cppcolormap.Greys_r
+    cppcolormap.Oranges_r
+    cppcolormap.Purples_r
+    cppcolormap.Reds_r
+    cppcolormap.BuPu_r
+    cppcolormap.GnBu_r
+    cppcolormap.PuBu_r
+    cppcolormap.PuBuGn_r
+    cppcolormap.PuRd_r
+    cppcolormap.RdPu_r
+    cppcolormap.OrRd_r
+    cppcolormap.RdOrYl_r
+    cppcolormap.YlGn_r
+    cppcolormap.YlGnBu_r
+    cppcolormap.YlOrRd_r
+    cppcolormap.BrBG_r
+    cppcolormap.PuOr_r
+    cppcolormap.RdBu_r
+    cppcolormap.RdGy_r
+    cppcolormap.RdYlBu_r
+    cppcolormap.RdYlGn_r
+    cppcolormap.PiYG_r
+    cppcolormap.PRGn_r
+    cppcolormap.spring_r
+    cppcolormap.summer_r
+    cppcolormap.autumn_r
+    cppcolormap.winter_r
+    cppcolormap.bone_r
+    cppcolormap.cool_r
+    cppcolormap.hot_r
+    cppcolormap.copper_r
+    cppcolormap.hsv_r
+    cppcolormap.nipy_spectral_r
+    cppcolormap.terrain_r
+    cppcolormap.seismic_r
+    cppcolormap.afmhot_r
+    cppcolormap.magma_r
+    cppcolormap.inferno_r
+    cppcolormap.plasma_r
+    cppcolormap.viridis_r
+    cppcolormap.jet_r
+    cppcolormap.xterm_r
+    cppcolormap.tue_r
+
+Details
+=======
+
+.. automodule:: cppcolormap
     :members:
     :special-members:
     :undoc-members:
diff --git a/docs/conf.py b/docs/conf.py
@@ -5,7 +5,7 @@
 # Project information
 
 project = "cppcolormap"
-copyright = "2021, Tom de Geus"
+copyright = "2021-2022, Tom de Geus"
 author = "Tom de Geus"
 
 # Build Python module
diff --git a/python/main.cpp b/python/main.cpp
@@ -12,18 +12,43 @@
 namespace py = pybind11;
 
 #define DOC(function) \
-    (std::string("See documentation of underlying C++ API: :cpp:func:`cppcolormap::") + \
+    (std::string("See documentation of C++ API: :cpp:func:`cppcolormap::") + \
      std::string(function) + std::string("`")) \
         .c_str()
 
 #define ENUM(function) \
-    (std::string("See documentation of underlying C++ API: :cpp:enum:`cppcolormap::") + \
+    (std::string("See documentation of C++ API: :cpp:enum:`cppcolormap::") + \
      std::string(function) + std::string("`")) \
         .c_str()
 
+/**
+Overrides the `__name__` of a module.
+Classes defined by pybind11 use the `__name__` of the module as of the time they are defined,
+which affects the `__repr__` of the class type objects.
+*/
+class ScopedModuleNameOverride {
+public:
+    explicit ScopedModuleNameOverride(py::module m, std::string name) : module_(std::move(m))
+    {
+        original_name_ = module_.attr("__name__");
+        module_.attr("__name__") = name;
+    }
+    ~ScopedModuleNameOverride()
+    {
+        module_.attr("__name__") = original_name_;
+    }
+
+private:
+    py::module module_;
+    py::object original_name_;
+};
+
 PYBIND11_MODULE(_cppcolormap, m)
 {
 
+    // Ensure members to display as `cppcolormap.X` rather than `cppcolormap._cppcolormap.X`
+    ScopedModuleNameOverride name_override(m, "cppcolormap");
+
     xt::import_numpy();
 
     m.doc() = "Library with colormaps";
@@ -271,6 +296,6 @@ PYBIND11_MODULE(_cppcolormap, m)
         .value("perceptual", cppcolormap::metric::perceptual)
         .export_values();
 
-    m.def("match", &cppcolormap::match);
+    m.def("match", &cppcolormap::match, DOC("match"));
 
 } // PYBIND11_MODULE
