diff --git a/docs/doc_build_instructions.md b/docs/doc_build_instructions.md new file mode 100644 index 000000000..9df7587e2 --- /dev/null +++ b/docs/doc_build_instructions.md @@ -0,0 +1,11 @@ +1. The API doc files are autogenerated using `source/generate_api.py` + +``` +python source/generate_api.py +``` + +2. make the docs + +make html -j24 + + diff --git a/docs/source/_templates/autosummary/method.rst b/docs/source/_templates/autosummary/method.rst new file mode 100644 index 000000000..306d2aab5 --- /dev/null +++ b/docs/source/_templates/autosummary/method.rst @@ -0,0 +1,5 @@ +{{ name | escape | underline}} + +.. currentmodule:: {{ module }} + +.. automethod:: {{ objname }} diff --git a/docs/source/_templates/autosummary/property.rst b/docs/source/_templates/autosummary/property.rst new file mode 100644 index 000000000..c31bebe07 --- /dev/null +++ b/docs/source/_templates/autosummary/property.rst @@ -0,0 +1,5 @@ +{{ name | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoproperty:: {{ objname }} diff --git a/docs/source/api/layouts/gridplot.rst b/docs/source/api/layouts/gridplot.rst index f34d0b8d1..87a787b12 100644 --- a/docs/source/api/layouts/gridplot.rst +++ b/docs/source/api/layouts/gridplot.rst @@ -35,64 +35,3 @@ Methods GridPlot.render GridPlot.show -======= -Subplot -======= -.. currentmodule:: fastplotlib.layouts._subplot - -Constructor -~~~~~~~~~~~ -.. autosummary:: - :toctree: Subplot_api - - Subplot - -Properties -~~~~~~~~~~ -.. autosummary:: - :toctree: Subplot_api - - Subplot.camera - Subplot.canvas - Subplot.controller - Subplot.graphics - Subplot.name - Subplot.parent - Subplot.position - Subplot.renderer - Subplot.scene - Subplot.selectors - Subplot.viewport - -Methods -~~~~~~~ -.. autosummary:: - :toctree: Subplot_api - - Subplot.add_animations - Subplot.add_graphic - Subplot.add_heatmap - Subplot.add_histogram - Subplot.add_image - Subplot.add_line - Subplot.add_line_collection - Subplot.add_line_stack - Subplot.add_scatter - Subplot.add_text - Subplot.auto_scale - Subplot.center_graphic - Subplot.center_scene - Subplot.center_title - Subplot.clear - Subplot.delete_graphic - Subplot.get_rect - Subplot.insert_graphic - Subplot.map_screen_to_world - Subplot.remove_animation - Subplot.remove_graphic - Subplot.render - Subplot.set_axes_visibility - Subplot.set_grid_visibility - Subplot.set_title - Subplot.set_viewport_rect - diff --git a/docs/source/api/layouts/subplot.rst b/docs/source/api/layouts/subplot.rst new file mode 100644 index 000000000..adab809c7 --- /dev/null +++ b/docs/source/api/layouts/subplot.rst @@ -0,0 +1,66 @@ +.. _api.Subplot: + +Subplot +******* + +======= +Subplot +======= +.. currentmodule:: fastplotlib.layouts._subplot + +Constructor +~~~~~~~~~~~ +.. autosummary:: + :toctree: Subplot_api + + Subplot + +Properties +~~~~~~~~~~ +.. autosummary:: + :toctree: Subplot_api + + Subplot.camera + Subplot.canvas + Subplot.controller + Subplot.graphics + Subplot.name + Subplot.parent + Subplot.position + Subplot.renderer + Subplot.scene + Subplot.selectors + Subplot.viewport + +Methods +~~~~~~~ +.. autosummary:: + :toctree: Subplot_api + + Subplot.add_animations + Subplot.add_graphic + Subplot.add_heatmap + Subplot.add_histogram + Subplot.add_image + Subplot.add_line + Subplot.add_line_collection + Subplot.add_line_stack + Subplot.add_scatter + Subplot.add_text + Subplot.auto_scale + Subplot.center_graphic + Subplot.center_scene + Subplot.center_title + Subplot.clear + Subplot.delete_graphic + Subplot.get_rect + Subplot.insert_graphic + Subplot.map_screen_to_world + Subplot.remove_animation + Subplot.remove_graphic + Subplot.render + Subplot.set_axes_visibility + Subplot.set_grid_visibility + Subplot.set_title + Subplot.set_viewport_rect + diff --git a/docs/source/api/utils.rst b/docs/source/api/utils.rst new file mode 100644 index 000000000..6222e22c6 --- /dev/null +++ b/docs/source/api/utils.rst @@ -0,0 +1,6 @@ +fastplotlib.utils +***************** + +.. currentmodule:: fastplotlib.utils +.. automodule:: fastplotlib.utils.functions + :members: diff --git a/docs/source/conf.py b/docs/source/conf.py index d65ea7193..77bd6be62 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -44,6 +44,7 @@ autodoc_member_order = 'groupwise' autoclass_content = "both" +add_module_names = False autodoc_typehints = "description" autodoc_typehints_description_target = "documented_params" diff --git a/docs/source/generate_rst.py b/docs/source/generate_api.py similarity index 89% rename from docs/source/generate_rst.py rename to docs/source/generate_api.py index 3f9c7ac83..05e8b0f1c 100644 --- a/docs/source/generate_rst.py +++ b/docs/source/generate_api.py @@ -8,6 +8,8 @@ from fastplotlib import graphics from fastplotlib.graphics import _features, selectors from fastplotlib import widgets +from fastplotlib import utils + current_dir = Path(__file__).parent.resolve() @@ -107,6 +109,20 @@ def generate_class( return out +def generate_functions_module(module, name: str): + underline = "*" * len(name) + out = ( + f"{name}\n" + f"{underline}\n" + f"\n" + f".. currentmodule:: {name}\n" + f".. automodule:: {module.__name__}\n" + f" :members:\n" + ) + + return out + + def generate_page( page_name: str, modules: List[str], @@ -138,11 +154,18 @@ def main(): generate_page( page_name="GridPlot", - classes=[fastplotlib.GridPlot, Subplot], - modules=["fastplotlib", "fastplotlib.layouts._subplot"], + classes=[fastplotlib.GridPlot], + modules=["fastplotlib"], source_path=LAYOUTS_DIR.joinpath("gridplot.rst") ) + generate_page( + page_name="Subplot", + classes=[Subplot], + modules=["fastplotlib.layouts._subplot"], + source_path=LAYOUTS_DIR.joinpath("subplot.rst") + ) + # the rest of this is a mess and can be refactored later graphic_classes = [ @@ -260,6 +283,12 @@ def main(): modules=["fastplotlib"], source_path=WIDGETS_DIR.joinpath(f"{widget_cls.__name__}.rst") ) + ############################################################################## + + utils_str = generate_functions_module(utils.functions, "fastplotlib.utils") + + with open(API_DIR.joinpath("utils.rst"), "w") as f: + f.write(utils_str) if __name__ == "__main__": diff --git a/docs/source/index.rst b/docs/source/index.rst index 99f342fb9..7e1d3865a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,10 +18,12 @@ Welcome to fastplotlib's documentation! Plot Gridplot + Subplot Graphics Graphic Features Selectors Widgets + Utils Summary ======= diff --git a/fastplotlib/layouts/_subplot.py b/fastplotlib/layouts/_subplot.py index 1ed52bc7c..c38510acf 100644 --- a/fastplotlib/layouts/_subplot.py +++ b/fastplotlib/layouts/_subplot.py @@ -43,6 +43,9 @@ def __init__( General plot object that composes a ``Gridplot``. Each ``Gridplot`` instance will have [n rows, n columns] of subplots. + .. important:: + ``Subplot`` is not meant to be constructed directly, it only exists as part of a ``GridPlot`` + Parameters ---------- position: int tuple, optional diff --git a/fastplotlib/utils/functions.py b/fastplotlib/utils/functions.py index f4d6ac4f1..3013559d5 100644 --- a/fastplotlib/utils/functions.py +++ b/fastplotlib/utils/functions.py @@ -149,9 +149,19 @@ def make_colors_dict(labels: iter, cmap: str, **kwargs) -> OrderedDict: def quick_min_max(data: np.ndarray) -> Tuple[float, float]: - # adapted from pyqtgraph.ImageView - # Estimate the min/max values of *data* by subsampling. - # Returns [(min, max), ...] with one item per channel + """ + Adapted from pyqtgraph.ImageView. + Estimate the min/max values of *data* by subsampling. + + Parameters + ---------- + data: np.ndarray or array-like with `min` and `max` attributes + + Returns + ------- + (float, float) + (min, max) + """ if hasattr(data, "min") and hasattr(data, "max"): # if value is pre-computed @@ -170,9 +180,26 @@ def quick_min_max(data: np.ndarray) -> Tuple[float, float]: def make_pygfx_colors(colors, n_colors): - """parse and make colors array using pyfx.Color""" + """ + Parse and make colors array using pyfx.Color + + Parameters + ---------- + colors: str, list, tuple, or np.ndarray + pygfx parseable color + + n_colors: int + number of repeats of the color + + Returns + ------- + np.ndarray + shape is [n_colors, 4], i.e. [n_colors, RGBA] + """ + c = Color(colors) colors_array = np.repeat(np.array([c]), n_colors, axis=0) + return colors_array