|
| 1 | +# -- Path setup -------------------------------------------------------------- |
| 2 | +import inspect |
| 3 | +import os |
| 4 | +import sys |
| 5 | + |
| 6 | +import numpy as np |
| 7 | + |
| 8 | +import blosc2 |
| 9 | + |
| 10 | + |
| 11 | +def genbody(f, func_list, lib="blosc2"): |
| 12 | + for func in func_list: |
| 13 | + f.write(f" {func}\n") |
| 14 | + |
| 15 | + f.write("\n\n\n") |
| 16 | + for func in func_list: |
| 17 | + f.write(f".. autofunction:: {lib}.{func}\n") |
| 18 | + |
| 19 | + |
| 20 | +sys.path.insert(0, os.path.abspath(os.path.dirname(blosc2.__file__))) |
| 21 | + |
| 22 | +project = "Python-Blosc2" |
| 23 | +copyright = "2019-present, The Blosc Developers" |
| 24 | +author = "The Blosc Developers" |
| 25 | +extensions = [ |
| 26 | + "sphinx.ext.autosummary", |
| 27 | + "sphinx.ext.autodoc", |
| 28 | + "sphinx.ext.intersphinx", |
| 29 | + "sphinx.ext.napoleon", |
| 30 | + "sphinx.ext.linkcode", |
| 31 | + "numpydoc", |
| 32 | + "myst_parser", |
| 33 | + "sphinx_paramlinks", |
| 34 | + "sphinx_design", |
| 35 | + "nbsphinx", |
| 36 | + # For some reason, the following extensions are not working |
| 37 | + # "IPython.sphinxext.ipython_directive", |
| 38 | + # "IPython.sphinxext.ipython_console_highlighting", |
| 39 | +] |
| 40 | +source_suffix = [".rst", ".md"] |
| 41 | +html_theme = "furo" |
| 42 | +html_static_path = ["_static"] |
| 43 | +html_css_files = [ |
| 44 | + "css/custom.css", |
| 45 | + "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css", |
| 46 | +] |
| 47 | +html_logo = "_static/blosc-logo_256.png" |
| 48 | +# Just use the favicon from the parent project |
| 49 | +# html_favicon = "_static/blosc-logo_128.png" |
| 50 | +html_favicon = "_static/blosc-favicon_64x64.png" |
| 51 | +html_theme_options = { |
| 52 | + "logo": { |
| 53 | + "link": "/index", |
| 54 | + "alt_text": "Blosc", |
| 55 | + }, |
| 56 | + "icon_links": [ |
| 57 | + { |
| 58 | + "name": "GitHub", |
| 59 | + "url": "https://github.com/Blosc/python-blosc2", |
| 60 | + "icon": "fab fa-github-square", |
| 61 | + }, |
| 62 | + { |
| 63 | + "name": "Mastodon", |
| 64 | + "url": "https://fosstodon.org/@Blosc2", |
| 65 | + "icon": "fab fa-mastodon", |
| 66 | + }, |
| 67 | + { |
| 68 | + "name": "Bluesky", |
| 69 | + "url": "https://bsky.app/profile/blosc.org", |
| 70 | + "icon": "fas fa-cloud-sun", |
| 71 | + }, |
| 72 | + ], |
| 73 | + "external_links": [ |
| 74 | + {"name": "C-Blosc2", "url": "/c-blosc2/c-blosc2.html"}, |
| 75 | + {"name": "Python-Blosc2", "url": "/python-blosc2/"}, |
| 76 | + {"name": "Donate to Blosc", "url": "/pages/donate/"}, |
| 77 | + ], |
| 78 | +} |
| 79 | + |
| 80 | +exclude_patterns = ["_build", ".DS_Store", "**.ipynb_checkpoints"] |
| 81 | + |
| 82 | +html_show_sourcelink = False |
| 83 | + |
| 84 | +autosummary_generate_overwrite = False |
| 85 | +autosummary_generate = True |
| 86 | + |
| 87 | +# GENERATE ufuncs.rst |
| 88 | +blosc2_ufuncs = [] |
| 89 | +for name, obj in vars(np).items(): |
| 90 | + if isinstance(obj, np.ufunc) and hasattr(blosc2, name): |
| 91 | + blosc2_ufuncs.append(name) |
| 92 | + |
| 93 | +with open("reference/ufuncs.rst", "w") as f: |
| 94 | + f.write( |
| 95 | + """Universal Functions (`ufuncs`) |
| 96 | +------------------------------ |
| 97 | +
|
| 98 | +The following elementwise functions can be used for computing with any of :ref:`NDArray <NDArray>`, :ref:`C2Array <C2Array>`, :ref:`NDField <NDField>` and :ref:`LazyExpr <LazyExpr>`. |
| 99 | +
|
| 100 | +Their result is always a :ref:`LazyExpr` instance, which can be evaluated (with ``compute`` or ``__getitem__``) to get the actual values of the computation. |
| 101 | +
|
| 102 | +Note: The functions ``conj``, ``real``, ``imag``, ``contains``, ``where`` are not technically ufuncs. |
| 103 | +
|
| 104 | +.. currentmodule:: blosc2 |
| 105 | +
|
| 106 | +.. autosummary:: |
| 107 | +
|
| 108 | +""" |
| 109 | + ) |
| 110 | + genbody(f, blosc2_ufuncs) |
| 111 | + |
| 112 | +# GENERATE additional_funcs.rst |
| 113 | +blosc2_addfuncs = sorted(["conj", "real", "imag", "contains", "where", "clip", "round"]) |
| 114 | +blosc2_dtypefuncs = sorted(["astype", "can_cast", "result_type", "isdtype"]) |
| 115 | + |
| 116 | +with open("reference/additional_funcs.rst", "w") as f: |
| 117 | + f.write( |
| 118 | + """Additional Functions and Type Utilities |
| 119 | +======================================= |
| 120 | +
|
| 121 | +Functions |
| 122 | +--------- |
| 123 | +
|
| 124 | +The following functions can also be used for computing with any of :ref:`NDArray <NDArray>`, :ref:`C2Array <C2Array>`, :ref:`NDField <NDField>` and :ref:`LazyExpr <LazyExpr>`. |
| 125 | +
|
| 126 | +Their result is typically a :ref:`LazyExpr` instance, which can be evaluated (with ``compute`` or ``__getitem__``) to get the actual values of the computation. |
| 127 | +
|
| 128 | +.. currentmodule:: blosc2 |
| 129 | +
|
| 130 | +.. autosummary:: |
| 131 | +
|
| 132 | +""" |
| 133 | + ) |
| 134 | + genbody(f, blosc2_addfuncs) |
| 135 | + f.write( |
| 136 | + """Type Utilities |
| 137 | +-------------- |
| 138 | +
|
| 139 | +The following functions are useful for working with datatypes. |
| 140 | +
|
| 141 | +.. currentmodule:: blosc2 |
| 142 | +
|
| 143 | +.. autosummary:: |
| 144 | +
|
| 145 | +""" |
| 146 | + ) |
| 147 | + genbody(f, blosc2_dtypefuncs) |
| 148 | + |
| 149 | +# GENERATE index_funcs.rst |
| 150 | +blosc2_indexfuncs = sorted( |
| 151 | + [ |
| 152 | + "count_nonzero", |
| 153 | + "squeeze", |
| 154 | + "expand_dims", |
| 155 | + "sort", |
| 156 | + "take", |
| 157 | + "take_along_axis", |
| 158 | + "broadcast_to", |
| 159 | + "meshgrid", |
| 160 | + "indices", |
| 161 | + ] |
| 162 | +) |
| 163 | + |
| 164 | +with open("reference/index_funcs.rst", "w") as f: |
| 165 | + f.write( |
| 166 | + """Indexing Functions and Utilities |
| 167 | +======================================= |
| 168 | +
|
| 169 | +The following functions are useful for performing indexing and other associated operations. |
| 170 | +
|
| 171 | +.. currentmodule:: blosc2 |
| 172 | +
|
| 173 | +.. autosummary:: |
| 174 | +
|
| 175 | +""" |
| 176 | + ) |
| 177 | + genbody(f, blosc2_indexfuncs) |
| 178 | + |
| 179 | +# GENERATE linear_algebra.rst |
| 180 | +linalg_funcs = [ |
| 181 | + name |
| 182 | + for name, obj in vars(blosc2.linalg).items() |
| 183 | + if (inspect.isfunction(obj) and getattr(obj, "__doc__", None)) |
| 184 | +] |
| 185 | + |
| 186 | +with open("reference/linalg.rst", "w") as f: |
| 187 | + f.write( |
| 188 | + """Linear Algebra |
| 189 | +----------------- |
| 190 | +The following functions can be used for computing linear algebra operations with :ref:`NDArray <NDArray>`. |
| 191 | +
|
| 192 | +.. currentmodule:: blosc2.linalg |
| 193 | +
|
| 194 | +.. autosummary:: |
| 195 | +
|
| 196 | +""" |
| 197 | + ) |
| 198 | + genbody(f, linalg_funcs, "blosc2.linalg") |
| 199 | + |
| 200 | +hidden = "_ignore_multiple_size" |
| 201 | + |
| 202 | + |
| 203 | +def linkcode_resolve(domain, info): |
| 204 | + if domain != "py": |
| 205 | + return None |
| 206 | + if not info["module"]: |
| 207 | + return None |
| 208 | + |
| 209 | + import importlib |
| 210 | + import inspect |
| 211 | + |
| 212 | + # Modify this to point to your package |
| 213 | + module_name = info["module"] |
| 214 | + full_name = info["fullname"] |
| 215 | + |
| 216 | + try: |
| 217 | + module = importlib.import_module(module_name) |
| 218 | + except ImportError: |
| 219 | + return None |
| 220 | + |
| 221 | + obj = module |
| 222 | + for part in full_name.split("."): |
| 223 | + obj = getattr(obj, part, None) |
| 224 | + if obj is None: |
| 225 | + return None |
| 226 | + |
| 227 | + try: |
| 228 | + fn = inspect.getsourcefile(obj) |
| 229 | + source, lineno = inspect.getsourcelines(obj) |
| 230 | + except Exception: |
| 231 | + return None |
| 232 | + |
| 233 | + # Replace this with your repo info |
| 234 | + github_base_url = "https://github.com/Blosc/python-blosc2/blob/main/" |
| 235 | + # Get the path relative to the repository root, not the module directory |
| 236 | + repo_root = os.path.abspath(os.path.join(os.path.dirname(blosc2.__file__), "..", "..")) |
| 237 | + relpath = os.path.relpath(fn, start=repo_root) |
| 238 | + return f"{github_base_url}{relpath}#L{lineno}" |
| 239 | + |
| 240 | + |
| 241 | +def process_sig(app, what, name, obj, options, signature, return_annotation): |
| 242 | + if signature and hidden in signature: |
| 243 | + signature = signature.split(hidden)[0] + ")" |
| 244 | + return (signature, return_annotation) |
| 245 | + |
| 246 | + |
| 247 | +def setup(app): |
| 248 | + app.connect("autodoc-process-signature", process_sig) |
| 249 | + |
| 250 | + |
| 251 | +# Allow errors (e.g. with numba asking for a specific numpy version) |
| 252 | +nbsphinx_allow_errors = True |
0 commit comments