Basic documentation

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)

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

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"]

docs/source/examples/index.md

@@ -0,0 +1,3 @@
+# Examples
+
+See the `/examples` folder containing jupyter notebooks demonstrating common types of orders.

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
+
+```

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` ([email protected]).
+
+### 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()
+```