Thanks to visit codestin.com
Credit goes to github.com

Skip to content

tweak docs, nicer now #274

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 6, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/doc_build_instructions.md
Original file line number Diff line number Diff line change
@@ -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


5 changes: 5 additions & 0 deletions docs/source/_templates/autosummary/method.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{{ name | escape | underline}}

.. currentmodule:: {{ module }}

.. automethod:: {{ objname }}
5 changes: 5 additions & 0 deletions docs/source/_templates/autosummary/property.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{{ name | escape | underline}}

.. currentmodule:: {{ module }}

.. autoproperty:: {{ objname }}
61 changes: 0 additions & 61 deletions docs/source/api/layouts/gridplot.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

66 changes: 66 additions & 0 deletions docs/source/api/layouts/subplot.rst
Original file line number Diff line number Diff line change
@@ -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

6 changes: 6 additions & 0 deletions docs/source/api/utils.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
fastplotlib.utils
*****************

.. currentmodule:: fastplotlib.utils
.. automodule:: fastplotlib.utils.functions
:members:
1 change: 1 addition & 0 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@

autodoc_member_order = 'groupwise'
autoclass_content = "both"
add_module_names = False

autodoc_typehints = "description"
autodoc_typehints_description_target = "documented_params"
Expand Down
33 changes: 31 additions & 2 deletions docs/source/generate_rst.py → docs/source/generate_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -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()

Expand Down Expand Up @@ -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],
Expand Down Expand Up @@ -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 = [
Expand Down Expand Up @@ -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__":
Expand Down
2 changes: 2 additions & 0 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,12 @@ Welcome to fastplotlib's documentation!

Plot <api/layouts/plot>
Gridplot <api/layouts/gridplot>
Subplot <api/layouts/subplot>
Graphics <api/graphics/index>
Graphic Features <api/graphic_features/index>
Selectors <api/selectors/index>
Widgets <api/widgets/index>
Utils <api/utils>

Summary
=======
Expand Down
3 changes: 3 additions & 0 deletions fastplotlib/layouts/_subplot.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
35 changes: 31 additions & 4 deletions fastplotlib/utils/functions.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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


Expand Down