aws / aws-step-functions-data-science-sdk-python

Step Functions Data Science SDK for building machine learning (ML) workflows and pipelines on AWS
Apache License 2.0
288 stars 88 forks source link

docs: Fix doc format and links #182

Closed ca-nguyen closed 2 years ago

ca-nguyen commented 2 years ago

Description

Fix docstring links and format

Fixes #(issue) - N/A

Why is the change necessary?

There are a few issues with certain docstrings links and format Generating the documentation locally with sphynx returned the following warnings

/README.rst:: WARNING: image file not readable: doc/images/create.png
/README.rst:: WARNING: image file not readable: doc/images/execute.png
/src/stepfunctions/steps/sagemaker.py:docstring of stepfunctions.steps.sagemaker.TrainingStep:26: WARNING: Unexpected indentation.
/src/stepfunctions/steps/sagemaker.py:docstring of stepfunctions.steps.sagemaker.TrainingStep:27: WARNING: Block quote ends without a blank line; unexpected unindent.
/src/stepfunctions/steps/sagemaker.py:docstring of stepfunctions.steps.sagemaker.TrainingStep:39: WARNING: Unknown target name: "createtrainingjob<https://docs.aws.amazon.com/sagemaker/latest/apireference/api_createtrainingjob.html>".
/src/stepfunctions/steps/sagemaker.py:docstring of stepfunctions.steps.sagemaker.TrainingStep:39: WARNING: Unknown target name: "placeholders<https://aws-step-functions-data-science-sdk.readthedocs.io/en/stable/placeholders.html?highlight=placeholder#stepfunctions.inputs.placeholder>".
/src/stepfunctions/steps/sagemaker.py:docstring of stepfunctions.steps.sagemaker.TransformStep:39: WARNING: Unknown target name: "createtransformjob<https://docs.aws.amazon.com/sagemaker/latest/apireference/api_createtransformjob.html>".
/src/stepfunctions/steps/sagemaker.py:docstring of stepfunctions.steps.sagemaker.TransformStep:39: WARNING: Unknown target name: "placeholders<https://aws-step-functions-data-science-sdk.readthedocs.io/en/stable/placeholders.html?highlight=placeholder#stepfunctions.inputs.placeholder>".
/src/stepfunctions/steps/sagemaker.py:docstring of stepfunctions.steps.sagemaker.TuningStep:28: WARNING: Unknown target name: "createhyperparametertuningjob<https://docs.aws.amazon.com/sagemaker/latest/apireference/api_createhyperparametertuningjob.html>".
/src/stepfunctions/steps/sagemaker.py:docstring of stepfunctions.steps.sagemaker.TuningStep:28: WARNING: Unknown target name: "placeholders<https://aws-step-functions-data-science-sdk.readthedocs.io/en/stable/placeholders.html?highlight=placeholder#stepfunctions.inputs.placeholder>".
/src/stepfunctions/steps/sagemaker.py:docstring of stepfunctions.steps.sagemaker.ModelStep:13: WARNING: Unknown target name: "createmodel<https://docs.aws.amazon.com/sagemaker/latest/apireference/api_createmodel.html>".
/src/stepfunctions/steps/sagemaker.py:docstring of stepfunctions.steps.sagemaker.ModelStep:13: WARNING: Unknown target name: "placeholders<https://aws-step-functions-data-science-sdk.readthedocs.io/en/stable/placeholders.html?highlight=placeholder#stepfunctions.inputs.placeholder>".
/src/stepfunctions/steps/sagemaker.py:docstring of stepfunctions.steps.sagemaker.ProcessingStep:32: WARNING: Unknown target name: "createprocessingjob<https://docs.aws.amazon.com/sagemaker/latest/apireference/api_createprocessingjob.html>".
/src/stepfunctions/steps/sagemaker.py:docstring of stepfunctions.steps.sagemaker.ProcessingStep:32: WARNING: Unknown target name: "placeholders<https://aws-step-functions-data-science-sdk.readthedocs.io/en/stable/placeholders.html?highlight=placeholder#stepfunctions.inputs.placeholder>".
/doc/services.rst:73: WARNING: Title underline too short.

Amazon EventBridge
-----------
/aws-step-functions-data-science-sdk-python/doc/services.rst:73: WARNING: Title underline too short.

Amazon EventBridge
-----------
/src/stepfunctions/steps/service.py:docstring of stepfunctions.steps.service.StepFunctionsStartExecutionStep:7: WARNING: Unexpected indentation.
/src/stepfunctions/steps/service.py:docstring of stepfunctions.steps.service.StepFunctionsStartExecutionStep:1: WARNING: Unknown target name: "manage aws step functions executions as an integrated service <https://docs.aws.amazon.com/step-functions/latest/dg/connect-stepfunctions.html".
/src/stepfunctions/steps/service.py:docstring of stepfunctions.steps.service.StepFunctionsStartExecutionStep:7: WARNING: Unknown target name: "run a job <https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-sync".
/src/stepfunctions/steps/service.py:docstring of stepfunctions.steps.service.StepFunctionsStartExecutionStep:7: WARNING: Unknown target name: "wait for a callback with the task token <https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-wait-token".
/src/stepfunctions/steps/service.py:docstring of stepfunctions.steps.service.StepFunctionsStartExecutionStep:7: WARNING: Unknown target name: "request response <https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-default".

Solution

Fixed the links and format per warnings

These warnings remain:

/README.rst:: WARNING: image file not readable: doc/images/create.png
/README.rst:: WARNING: image file not readable: doc/images/execute.png

Validated that the rst file is rendered properly and that the images are readable - these warnings only apply when rendering using Sphynx

How was this missed?

These doc changes have not been validated by generating the documentation locally before being merged - created a PR to include this step in the PR checklist and to add instructions on how to generate the docs locally in the CONTRIBUTING guide

Testing

Generate the Sphynx docs locally to validate links and doc format


Pull Request Checklist

Please check all boxes (including N/A items)

Testing

Documentation

Title and description


By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license.

StepFunctions-Bot commented 2 years ago

AWS CodeBuild CI Report

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository