diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..d0c3cbf10 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 000000000..747ffb7b3 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 000000000..23eca6489 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,64 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import sys +from pathlib import Path + +# Get the absolute path to the root of your project +project_root = Path(__file__).parents[2].resolve() + +# Add the project root and the src directory to the Python path +sys.path.insert(0, str(project_root)) +sys.path.insert(0, str(project_root / "src")) + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "Rapidata Python" +copyright = "2024, Rapidata" +author = "Rapidata" +release = "0.1.0" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["autoapi.extension", "sphinx.ext.viewcode", "myst_parser"] + +templates_path = ["_templates"] +exclude_patterns = [] + +nitpicky = True + +# -- MyST Parser configuration ----------------------------------------------- +# https://myst-parser.readthedocs.io/en/latest/configuration.html + +# Indicate that both .md and .rst files should be treated as sources +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} + +# Set heading anchor depth (1-6) +myst_heading_anchors = 3 + +# Enables auto-generated header anchors +myst_anchor_sections = True + +# Enables URL link resolution +myst_url_schemes = ["http", "https", "mailto"] + + +# -- AutoAPI configuration --------------------------------------------------- + +autoapi_dirs = ['../../rapidata'] +autoapi_type = "python" +# autoapi_keep_files = True + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "furo" +html_static_path = ["_static"] diff --git a/docs/source/examples/index.md b/docs/source/examples/index.md new file mode 100644 index 000000000..1e888ae19 --- /dev/null +++ b/docs/source/examples/index.md @@ -0,0 +1,3 @@ +# Examples + +See the `/examples` folder containing jupyter notebooks demonstrating common types of orders. \ No newline at end of file diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 000000000..6b0f73e77 --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,14 @@ + +# Rapidata Python Documentation + +Welcome! The Rapidata Python Client is a convenient way to interact with the Rapidata Web API from python applications. + +## Sections + +```{toctree} +:maxdepth: 1 + +quickstart +examples/index + +``` \ No newline at end of file diff --git a/docs/source/quickstart.md b/docs/source/quickstart.md new file mode 100644 index 000000000..97036d0e6 --- /dev/null +++ b/docs/source/quickstart.md @@ -0,0 +1,92 @@ +# Quickstart + +## Installation + +In the future: + +``` +pip install rapidata +``` + +## Usage + +Orders are managed throught the {py:class}`rapidata.rapidata_client.RapidataClient`. + +One can create client like this: + +``` +from rapidata.rapidata_client import RapidataClient + + +rapi = RapidataClient(client_id=CLIENT_ID, client_secret=CLIENT_SECRET) +``` + +Ask a Rapidata representative for your `CLIENT_ID` and `CLIENT_SECRET` (info@rapidata.ai). + +### Creating an Order + +Creating an order is done using the created `rapi` client. + +1. Create a new `OrderBuilder` {py:class}`rapidata.rapidata_client.order.rapidata_order_builder` and specify the name: + +``` +order_builder = rapi.new_order("Example Order") +``` + +2. Configure the order using a workflow. For example, the {py:class}`rapidata.rapidata_client.workflow.classify_workflow.ClassifyWorkflow` asks a question with multiple answer choices: + +``` +workflow = ClassifyWorkflow( + question="Who should be president?", + categories=["Kamala Harris", "Donald Trump"], + ) +``` + +Optionally, you can further configure the workflow by specifying the number of answers desired for each datapoint with this question: + +``` +workflow.referee(NaiveReferee(required_guesses=15)) +``` + +Now, set the `workflow` on the `order_builder`: +``` +order_builder.workflow(workflow) +``` + +3. Create the order +``` +order = order_builder.create() +``` + +4. Upload datapoints for which you want this question to be asked. For this case, we only upload one image: +``` +order.dataset.add_images_from_paths(["examples/data/kamala_trump.jpg"]) +``` +5. Submit the order: +``` +order.submit() +``` + + +### Short Form + +The `order_builder` and `workflow` support a fluent interface, which makes chaining of method calls possible. This allows to achieve everything in a short snippet: + +``` +order = ( + rapi.new_order( + name="Example Classify Order", + ) + .workflow( + ClassifyWorkflow( + question="Who should be president?", + categories=["Kamala Harris", "Donald Trump"], + ) + .referee(NaiveReferee(required_guesses=15)) + ) + .create() +) + +order.dataset.add_images_from_paths(["examples/data/kamala_trump.jpg"]) +order.submit() +``` \ No newline at end of file