diff --git a/docs/conf.py b/docs/conf.py index 939661a..2da64cf 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,6 +15,7 @@ extensions = [ "sphinx.ext.autodoc", "sphinx.ext.napoleon", + "sphinx_autodoc_typehints", "sphinx.ext.intersphinx", "sphinx.ext.todo", "sphinx.ext.coverage", @@ -62,6 +63,11 @@ } # -- Options for HTML output --------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -from sunpy_sphinx_theme.conf import * # NOQA +# The theme to use for HTML and HTML Help pages. +html_theme = "sphinx_book_theme" +html_theme_options = { + "repository_url": "https://github.com/Helioviewer-Project/python-api/", + "use_repository_button": True, + "extra_navbar": "", +} +html_title = "hvpy" diff --git a/hvpy/api_groups/jpeg2000/get_jp2_header.py b/hvpy/api_groups/jpeg2000/get_jp2_header.py index b432ccb..e14c227 100644 --- a/hvpy/api_groups/jpeg2000/get_jp2_header.py +++ b/hvpy/api_groups/jpeg2000/get_jp2_header.py @@ -5,15 +5,16 @@ class getJP2HeaderInputParameters(HvpyParameters): """ - Handles the input parameters of the getJP2Header API. + Handles the input parameters of the ``getJP2Header`` API. Attributes ---------- {Shared} - id : int + id Unique JP2 image identifier. - callback : str, optional + callback Wrap the response object in a function call of your choosing. + Default is `None` (no wrapping), optional. References ---------- diff --git a/hvpy/api_groups/jpeg2000/get_jp2_image.py b/hvpy/api_groups/jpeg2000/get_jp2_image.py index cc15876..8633d89 100644 --- a/hvpy/api_groups/jpeg2000/get_jp2_image.py +++ b/hvpy/api_groups/jpeg2000/get_jp2_image.py @@ -8,19 +8,21 @@ class getJP2ImageInputParameters(HvpyParameters): """ - Handles the input parameters of the getJP2Image API. + Handles the input parameters of the ``getJP2Image`` API. Attributes ---------- {Shared} - date : datetime.datetime - Desired date/time of the JP2 image. - sourceId : int + date + Desired datetime of the JP2 image. + sourceId Unique image datasource identifier. - jpip : bool, optional - Returns a JPIP URI instead of the binary data of the image if set to `True`, defaults to `False`. - json : bool, optional - Returns the JSON if set to `True`, defaults to `False`. + jpip + Returns a JPIP URI instead of the binary data of the image if set to True. + Default is `False`, optional. + json + Optionally, returns the JSON if set to `True`. + Default is `False`, optional. References ---------- diff --git a/hvpy/api_groups/jpeg2000/get_jpx.py b/hvpy/api_groups/jpeg2000/get_jpx.py index 8cd967f..7613b12 100644 --- a/hvpy/api_groups/jpeg2000/get_jpx.py +++ b/hvpy/api_groups/jpeg2000/get_jpx.py @@ -9,25 +9,31 @@ class getJPXInputParameters(HvpyParameters): """ - Handles the input parameters of the getJPX API. + Handles the input parameters of the ``getJPX`` API. Attributes ---------- {Shared} - startTime : datetime.datetime - Date/Time for the beginning of the JPX movie data. - endTime : datetime.datetime - Date/Time for the end of the JPX movie data. - sourceId : int + startTime + Datetime for the beginning of the JPX movie data. + endTime + Datetime for the end of the JPX movie data. + sourceId Unique image datasource identifier. - linked : bool, optional + linked Generate a linked JPX file containing image pointers instead of data for each individual frame in the series. - verbose : bool, optional - If set to true, the JSON response will include timestamps for each frame in the resulting movie and any warning messages associated with the request, in addition to the JPX movie file URI. - jpip : bool, optional - Optionally return a JPIP URI string instead of the binary data of the movie itself, or instead of an HTTP URI in the JSON response (if verbose is set to true). - cadence : int, optional + Default is `True`, optional. + verbose + if set to `True`, the JSON response will include timestamps for each frame in the resulting movie + and any warning messages associated with the request. + In addition to the JPX movie file URI. + Default is `False`, optional. + jpip + Return a JPIP URI string instead of the binary data of the movie itself, or instead of an HTTP URI in the JSON response (if ``verbose`` is set to `True`). + Default is `False`, optional. + cadence The desired amount of time (in seconds) between each frame in the movie. + Default is `None` (maximum cadence), optional. References ---------- diff --git a/hvpy/api_groups/jpeg2000/get_jpx_closest_to_mid_point.py b/hvpy/api_groups/jpeg2000/get_jpx_closest_to_mid_point.py index 228df19..213799c 100644 --- a/hvpy/api_groups/jpeg2000/get_jpx_closest_to_mid_point.py +++ b/hvpy/api_groups/jpeg2000/get_jpx_closest_to_mid_point.py @@ -9,23 +9,26 @@ class getJPXClosestToMidPointInputParameters(HvpyParameters): """ - Handles the input parameters of the getJPXClosestToMidPoint API. + Handles the input parameters of the ``getJPXClosestToMidPoint`` API. Attributes ---------- {Shared} - startTimes : datetime.datetime - Comma separated timestamps for the beginning of the JPX movie data. - endTimes : datetime.datetime - Comma separated timestamps for the end of the JPX movie data. - sourceId : int + startTimes + A list of datetimes for the beginning of the JPX movie data. + endTimes + A list of datetimes for the end of the JPX movie data. + sourceId Unique image datasource identifier. - linked : bool, optional + linked Generate a linked JPX file containing image pointers instead of data for each individual frame in the series. - verbose : bool, optional - If set to true, the JSON response will include timestamps for each frame in the resulting movie and any warning messages associated with the request, in addition to the JPX movie file URI. - jpip : bool, optional - Optionally return a JPIP URI string instead of the binary data of the movie itself, or instead of an HTTP URI in the JSON response (if verbose is set to true). + Default is `True`, optional. + verbose + If set, the JSON response will include timestamps for each frame in the resulting movie and any warning messages associated with the request, in addition to the JPX movie file URI. + Default is `False`, optional. + jpip + Return a JPIP URI string instead of the binary data of the movie itself, or instead of an HTTP URI in the JSON response (if ``verbose`` is set to `True`). + Default is `False`, optional. References ---------- diff --git a/hvpy/api_groups/jpeg2000/get_status.py b/hvpy/api_groups/jpeg2000/get_status.py index fe4c3ac..5796b7b 100644 --- a/hvpy/api_groups/jpeg2000/get_status.py +++ b/hvpy/api_groups/jpeg2000/get_status.py @@ -3,7 +3,7 @@ class getStatusInputParameters(HvpyParameters): """ - handles the input parameters of the getStatus API. + Handles the input parameters of the ``getStatus`` API. {Shared} References diff --git a/hvpy/api_groups/official_clients/get_closest_image.py b/hvpy/api_groups/official_clients/get_closest_image.py index 7887eb9..a056d3c 100644 --- a/hvpy/api_groups/official_clients/get_closest_image.py +++ b/hvpy/api_groups/official_clients/get_closest_image.py @@ -9,17 +9,18 @@ class getClosestImageInputParameters(HvpyParameters): """ - Handles the input parameters of the getClosestImage API. + Handles the input parameters of the ``getClosestImage`` API. Attributes ---------- {Shared} - date : datetime.datetime + date Date and time of the image. - sourceId : int + sourceId Unique image datasource identifier. - callback : str, optional - Wrap the response object in a function call of your choosing. + callback + Optionally, wrap the response object in a function call of your choosing. + Default is `None` (no wrapping), optional. References ---------- diff --git a/hvpy/api_groups/official_clients/get_data_sources.py b/hvpy/api_groups/official_clients/get_data_sources.py index 61d8842..2940944 100644 --- a/hvpy/api_groups/official_clients/get_data_sources.py +++ b/hvpy/api_groups/official_clients/get_data_sources.py @@ -5,17 +5,20 @@ class getDataSourcesInputParameters(HvpyParameters): """ - Handles the input parameters of the getDataSources API. + Handles the input parameters of the ``getDataSources`` API. Attributes ---------- {Shared} - verbose : bool, optional - Output the hierarchical list of available datasources in a format that is compatible with the JHelioviewer desktop client, default is False. - enable : str, optional - Comma-separated list of observatories to enable. - callback : str, optional - Wrap the response object in a function call of your choosing. + verbose + Output the hierarchical list of available datasources in a format that is compatible with the JHelioviewer desktop client. + Default is `False`, optional. + enable + Optionally, comma-separated list of observatories to enable. + Default is `None` (all observatories are enabled), optional. + callback + Optionally, wrap the response object in a function call of your choosing. + Default is `None` (no wrapping), optional. References ---------- diff --git a/hvpy/api_groups/screenshots/download_screenshot.py b/hvpy/api_groups/screenshots/download_screenshot.py index 41cbbe3..a777ebd 100644 --- a/hvpy/api_groups/screenshots/download_screenshot.py +++ b/hvpy/api_groups/screenshots/download_screenshot.py @@ -3,13 +3,13 @@ class downloadScreenshotInputParameters(HvpyParameters): """ - Handles the input parameters of the downloadScreenshot API. + Handles the input parameters of the ``downloadScreenshot`` API. Attributes ---------- {Shared} - id: int - Unique screenshot identifier (provided by the response to a takeScreenshot request). + id + Unique screenshot identifier (provided by the response to a ``takeScreenshot`` request). References ---------- diff --git a/hvpy/api_groups/screenshots/take_screenshot.py b/hvpy/api_groups/screenshots/take_screenshot.py index 579f751..73785d7 100644 --- a/hvpy/api_groups/screenshots/take_screenshot.py +++ b/hvpy/api_groups/screenshots/take_screenshot.py @@ -9,51 +9,78 @@ class takeScreenshotInputParameters(HvpyParameters): """ - Handles the input parameters of the takeScreenshot API. + Handles the input parameters of the ``takeScreenshot`` API. Attributes ---------- {Shared} - date : datetime.datetime - Desired date/time of the image. - imageScale : float + date + Desired datetime of the image. + imageScale Image scale in arcseconds per pixel. - layers : str + layers Image datasource layer(s) to include in the screenshot. - eventLabels : bool - Optionally annotate each event marker with a text label. - events : str, optional - List feature/event types and FRMs to use to annoate the movie. Use the empty string to indicate that no feature/event annotations should be shown. - scale : bool, optional - Optionally overlay an image scale indicator. - scaleType : str, optional - Image scale indicator. - scaleX : int, optional + events + List feature/event types and FRMs to use to annotate the movie. + Use the empty string to indicate that no feature/event annotations should be shown. + Default is `None`, optional. + eventLabels + Annotate each event marker with a text label. + Default is `False`, optional. + scale + Overlay an image scale indicator. + Default is `False`, optional. + scaleType + The Image scale indicator. + Default is `None`, optional. + scaleX Horizontal offset of the image scale indicator in arcseconds with respect to the center of the Sun. - scaleY : int, optional + Default is `None`, optional. + scaleY Vertical offset of the image scale indicator in arcseconds with respect to the center of the Sun. - width : str, optional - Width of the field of view in pixels. (Used in conjunction width x0,`y0`, and height). - height : str, optional - Height of the field of view in pixels. (Used in conjunction width x0,`y0`, and width). - x0 : str, optional - The horizontal offset of the center of the field of view from the center of the Sun. Used in conjunction with y0, width, and height. - y0 : str, optional - The vertical offset of the center of the field of view from the center of the Sun. Used in conjunction with x0, width, and height. - x1 : str, optional - The horizontal offset of the top-left corner of the field of view with respect to the center of the Sun (in arcseconds). Used in conjunction with y1, x2, and y2. - y1 : str, optional - The vertical offset of the top-left corner of the field of view with respect to the center of the Sun (in arcseconds). Used in conjunction with x1, x2, and y2. - x2 : str, optional - The horizontal offset of the bottom-right corner of the field of view with respect to the center of the Sun (in arcseconds). Used in conjunction with x1, y1, and y2. - y2 : str, optional - The vertical offset of the bottom-right corner of the field of view with respect to the center of the Sun (in arcseconds). Used in conjunction with x1, y1, and x2. - display : bool, optional - Set to true to directly output binary PNG image data. Default is `False` (which outputs a JSON object). - watermark : bool, optional - Optionally overlay a watermark consisting of a Helioviewer logo and the datasource abbreviation(s) and timestamp(s) displayed in the screenshot. - callback : str, optional + Default is `None`, optional. + width + Width of the field of view in pixels. + Used in conjunction width ``x0``,``y0``, and ``height``. + Default is `None`, optional. + height + Height of the field of view in pixels. + Used in conjunction width ``x0``,``y0``, and ``width``. + Default is `None`, optional. + x0 + The horizontal offset of the center of the field of view from the center of the Sun. + Used in conjunction with ``y0``, ``width``, and ``height``. + Default is `None`, optional. + y0 + The vertical offset of the center of the field of view from the center of the Sun. + Used in conjunction with ``x0``, ``width``, and ``height``. + Default is `None`, optional. + x1 + The horizontal offset of the top-left corner of the field of view with respect to the center of the Sun (in arcseconds). + Used in conjunction with ``y1``, ``x2``, and ``y2``. + Default is `None`, optional. + y1 + The vertical offset of the top-left corner of the field of view with respect to the center of the Sun (in arcseconds). + Used in conjunction with ``x1``, ``x2``, and ``y2``. + Default is `None`, optional. + x2 + The horizontal offset of the bottom-right corner of the field of view with respect to the center of the Sun (in arcseconds). + Used in conjunction with ``x1``, ``y1``, and ``y2``. + Default is `None`, optional. + y2 + The vertical offset of the bottom-right corner of the field of view with respect to the center of the Sun (in arcseconds). + Used in conjunction with ``x1``, ``y1``, and ``x2``. + Default is `None`, optional. + display + Set to true to directly output binary PNG image data. + Default is `False` (which outputs a JSON object), optional. + watermark + Overlay a watermark consisting of a Helioviewer logo, the datasource abbreviation(s) and timestamp(s) displayed in the screenshot. + Default is `False`, optional. + Optional. + callback Wrap the response object in a function call of your choosing. + Default is `None` (no wrapping), optional. References ---------- diff --git a/hvpy/core.py b/hvpy/core.py index 770ff41..1220142 100644 --- a/hvpy/core.py +++ b/hvpy/core.py @@ -13,9 +13,9 @@ def parse_response(response: requests.Response, output_type: OutputType) -> Unio Parameters ---------- - response : requests.Response + response The response from the API call. - output_type : hvpy.io.OutputType + output_type The output type. Returns @@ -39,7 +39,7 @@ def execute_api_call(input_parameters: HvpyParameters) -> Union[bytes, str, Dict Parameters ---------- - input_parameters : hvpy.io.HvpyParameters + input_parameters The input parameters. Returns diff --git a/hvpy/facade.py b/hvpy/facade.py index 4b26ea9..9b3cf21 100644 --- a/hvpy/facade.py +++ b/hvpy/facade.py @@ -74,7 +74,7 @@ def getJPXClosestToMidPoint( ) -> Union[bytes, str, Dict[str, Any]]: """ Generate and (optionally) download a custom JPX movie of the specified - datasource with one frame per pair of startTimes/endTimes parameters. + datasource with one frame per pair of start/endtimes given. Parameters ---------- @@ -165,9 +165,9 @@ def getClosestImage( callback: Optional[str] = None, ) -> Union[bytes, str, Dict[str, Any]]: """ - Find the image data that is closest to the requested date/time. Return the - associated metadata from the helioviewer database and the XML header of the - JPEG2000 image file. + Find the image data that is closest to the requested datetime. + + Return the associated metadata from the helioviewer database and the XML header of the JPEG2000 image file. Parameters ---------- @@ -284,8 +284,8 @@ def takeScreenshot( @add_shared_docstring(downloadScreenshotInputParameters) def downloadScreenshot(id: int) -> Union[bytes, str, Dict[str, Any]]: """ - Download a custom screenshot (that was generated using the `takeScreenshot` - API endpoint). + Download a custom screenshot that was generated using the + ``takeScreenshot`` API endpoint. Parameters ---------- diff --git a/setup.cfg b/setup.cfg index 3c615f7..73b0676 100644 --- a/setup.cfg +++ b/setup.cfg @@ -41,8 +41,9 @@ tests = pytest>=6.0 docs = sphinx + sphinx-autodoc-typehints sphinx-automodapi - sunpy-sphinx-theme + sphinx-book-theme [tool:pytest] testpaths = "hvpy" "docs"