feat: add docs, rename sdk submodule -> core

CONTRIBUTING.md

@@ -0,0 +1,17 @@
+Developer workflows are run with [`just`](https://github.com/casey/just). You can use `just -l` to list commands, and view the `justfile` for the commands.
+
+We use `poetry` for packaging and developing. Add a depenency with `poetry add dep`, or `poetry add --group dev dep` for a dev dependency.
+
+We use `ruff` for formatting and imports, `mypy` for static typing, and `pytest` for testing.
+
+To run all tests and checks: `just verify`. To include e2e tests (for Nominal developers): `just verify-e2e`.
+
+As a rule, all tools should be configured via pyproject.toml, and should prefer configuration over parameters for project information. For example, `poetry run mypy` should work without having to run `poetry run mypy nominal`.
+
+Tests are written with `pytest`. By default, `pytest` runs all the tests in `tests/` except the end-to-end (e2e) tests in `tests/e2e`. To run e2e tests, `pytest` needs to be passed the e2e test directory with command-line arguments for connecting to the Nominal platform to test against. The e2e tests can be ran manually as:
+
+```sh
+poetry run pytest tests/e2e --auth-token AUTH_TOKEN [--base-url BASE_URL]
+```
+
+or simply with `just test-e2e <token>`.

README.md

@@ -14,70 +14,6 @@ python3 -m pip install nominal --upgrade
 import nominal as nm
 ```
 
-### Connecting to Nominal
-
-Retrieve your API key from [/sandbox](https://app.gov.nominal.io/sandbox) on your Nominal tenant. Then, set the Nominal connection parameters in a terminal:
-
-```sh
-python3 -m nominal auth set-token
-```
-
-This sets the auth token on your system, which can be updated with the same command as needed.
-
-### Upload a Dataset
-
-```py
-dataset = nm.upload_csv(
-    '../path/to/data.csv',
-    name='Stand A',
-    timestamp_column='timestamp',
-    timestamp_type='epoch_seconds',
-)
-print('Uploaded dataset:', dataset.rid)
-```
-
-### Create a Run
-
-```py
-run = nm.create_run(
-    name='Run A',
-    start='2024-09-09T12:35:00Z',
-    start='2024-09-09T13:18:00Z',
-)
-print("Created run:", run.rid)
-```
-
-### Update metadata of an existing Run
-
-```py
-run = nm.get_run('ri.scout.gov-staging.run.ce205f7e-9ef1-4a8b-92ae-11edc77441c6')
-run.update(name='New Run Title')
-```
-
-### Change default Nominal tenant
-
-By default, the library uses `https://api.gov.nominal.io/api` as the base url to the Nominal platform. Your scripts can change the URL they use with `set_base_url()`. For example, to use the staging URL:
-
-```py
-nm.set_base_url('https://api-staging.gov.nominal.io/api')
-```
-
 ## Development
 
-Developer workflows are run with [`just`](https://github.com/casey/just). You can use `just -l` to list commands, and view the `justfile` for the commands.
-
-We use `poetry` for packaging and developing. Add a depenency with `poetry add dep`, or `poetry add --group dev dep` for a dev dependency.
-
-We use `ruff` for formatting and imports, `mypy` for static typing, and `pytest` for testing.
-
-To run all tests and checks: `just verify`. To include e2e tests (for Nominal developers): `just verify-e2e`.
-
-As a rule, all tools should be configured via pyproject.toml, and should prefer configuration over parameters for project information. For example, `poetry run mypy` should work without having to run `poetry run mypy nominal`.
-
-Tests are written with `pytest`. By default, `pytest` runs all the tests in `tests/` except the end-to-end (e2e) tests in `tests/e2e`. To run e2e tests, `pytest` needs to be passed the e2e test directory with command-line arguments for connecting to the Nominal platform to test against. The e2e tests can be ran manually as:
-
-```sh
-poetry run pytest tests/e2e --auth-token AUTH_TOKEN [--base-url BASE_URL]
-```
-
-or simply with `just test-e2e <token>`.
+See [CONTRIBUTING.md](CONTRIBUTING.md).

docs/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

docs/contributing.md

@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"

docs/css/mkdocstrings.css

@@ -0,0 +1,5 @@
+/* Indentating children (e.g. methods are indented below the class) */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: .05rem solid var(--md-typeset-table-color);
+}

docs/index.md

@@ -0,0 +1,13 @@
+# Welcome to the Nominal Python SDK documentation!
+
+```py
+import nominal as nm
+```
+
+The main components of the SDK are:
+
+- An object-oriented interface for direct integration with the Nominal platform
+- A high-level, function oriented interface for common Nominal interactions
+- The `nom` CLI for common Nominal interactions
+
+Use the navigation bar above to see examples and reference documentation.

docs/license.md

@@ -0,0 +1 @@
+--8<-- "LICENSE"

docs/reference/core.md

@@ -0,0 +1 @@
+::: nominal.core

docs/reference/exceptions.md

@@ -0,0 +1 @@
+::: nominal.exceptions

docs/reference/nom-cli.md

@@ -0,0 +1,9 @@
+::: mkdocs-click
+    :module: nominal.cli
+    :command: nom
+    :style: table
+
+<!--
+    :style: "table" - as opposed to "plain"
+    "plain" looks like the normal help output, which I prefer, except it doesn't show default args!
+-->

docs/reference/toplevel.md

@@ -0,0 +1,13 @@
+::: nominal
+    options:
+      filters:
+      - "!^_" # default filter
+      - "!Attachment"
+      - "!Dataset"
+      - "!NominalClient"
+      - "!Run"
+
+<!--
+  Eventually we can use `summary` over `filters` when it moves from Sponsors only to GA:
+  https://mkdocstrings.github.io/python/usage/configuration/members/#summary
+-->

docs/usage/examples.md

@@ -0,0 +1,48 @@
+
+### Connecting to Nominal
+
+Retrieve your API key from [/sandbox](https://app.gov.nominal.io/sandbox) on your Nominal tenant. Then, set the Nominal connection parameters in a terminal:
+
+```sh
+python3 -m nominal auth set-token
+```
+
+This sets the auth token on your system, which can be updated with the same command as needed.
+
+### Upload a Dataset
+
+```py
+dataset = nm.upload_csv(
+    '../path/to/data.csv',
+    name='Stand A',
+    timestamp_column='timestamp',
+    timestamp_type='epoch_seconds',
+)
+print('Uploaded dataset:', dataset.rid)
+```
+
+### Create a Run
+
+```py
+run = nm.create_run(
+    name='Run A',
+    start='2024-09-09T12:35:00Z',
+    start='2024-09-09T13:18:00Z',
+)
+print("Created run:", run.rid)
+```
+
+### Update metadata of an existing Run
+
+```py
+run = nm.get_run('ri.scout.gov-staging.run.ce205f7e-9ef1-4a8b-92ae-11edc77441c6')
+run.update(name='New Run Title')
+```
+
+### Change default Nominal tenant
+
+By default, the library uses `https://api.gov.nominal.io/api` as the base url to the Nominal platform. Your scripts can change the URL they use with `set_base_url()`. For example, to use the staging URL:
+
+```py
+nm.set_base_url('https://api-staging.gov.nominal.io/api')
+```

mkdocs.yml

@@ -0,0 +1,123 @@
+site_name: "Nominal Python SDK"
+repo_url: "https://github.com/nominal-io/nominal-client"
+repo_name: "nominal-io/nominal-client"
+site_dir: "site"
+watch: [mkdocs.yml, README.md, CHANGELOG.md, nominal]
+copyright: Copyright © 2024 Nominal, Inc.
+edit_uri: edit/main/docs/
+
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+
+extra_css:
+  - css/mkdocstrings.css
+
+nav:
+  - Home:
+      - Overview: index.md
+      - Changelog: changelog.md
+      - License: license.md
+  - Usage:
+      - Examples: usage/examples.md
+  - Reference:
+      - High-level SDK: reference/toplevel.md
+      - Core SDK: reference/core.md
+      - Exceptions: reference/exceptions.md
+      - nom cli: reference/nom-cli.md
+  - Development:
+      - Contributing: contributing.md
+  - Nominal: https://nominal.io
+
+theme:
+  name: material
+  palette:
+    scheme: default
+  logo: logo.svg
+  features:
+    - content.action.edit
+    - content.action.view
+    - content.code.annotate # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-annotations
+    - content.code.copy
+    - content.tooltips
+    - navigation.footer
+    - navigation.indexes
+    - navigation.sections
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.top
+    - search.highlight
+    - search.suggest
+    - toc.follow
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-night
+        name: Switch to system preference
+
+markdown_extensions:
+  - admonition
+  - footnotes
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      pygments_lang_class: true
+  - pymdownx.magiclink
+  - pymdownx.snippets:
+      base_path: [!relative $config_dir]
+      check_paths: true
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+      slugify: !!python/object/apply:pymdownx.slugs.slugify
+        kwds:
+          case: lower
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+  - toc:
+      permalink: "¤"
+  - attr_list
+  - mkdocs-click
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          import:
+            - https://docs.python.org/3/objects.inv
+          options:
+            docstring_options:
+              ignore_init_summary: true
+            docstring_section_style: list
+            filters: ["!^_"]
+            heading_level: 1
+            inherited_members: true
+            merge_init_into_class: true
+            parameter_headings: true
+            separate_signature: true
+            line_length: 72
+            show_root_heading: true
+            show_root_full_path: false
+            show_signature_annotations: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            signature_crossrefs: true
+            show_source: false
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/nominal-io
+    - icon: fontawesome/brands/python
+      link: https://pypi.org/project/nominal/

nominal/__init__.py

@@ -1,3 +1,4 @@
+from .core import Attachment, Dataset, NominalClient, Run
 from .nominal import (
     create_run,
     create_run_csv,
@@ -13,7 +14,6 @@
     upload_pandas,
     upload_polars,
 )
-from .sdk import Attachment, Dataset, NominalClient, Run
 
 __all__ = [
     "set_base_url",

nominal/cli/__init__.py

@@ -3,12 +3,12 @@
 from . import attachment, auth, dataset, run
 
 
-@click.group(context_settings={"show_default": True})
+@click.group(context_settings={"show_default": True, "help_option_names": ("-h", "--help")})
 def nom() -> None:
     pass
 
 
-nom.add_command(attachment.attachment_cmd, "attachment")
-nom.add_command(auth.auth_cmd, "auth")
-nom.add_command(dataset.dataset_cmd, "dataset")
-nom.add_command(run.run_cmd, "run")
+nom.add_command(attachment.attachment_cmd)
+nom.add_command(auth.auth_cmd)
+nom.add_command(dataset.dataset_cmd)
+nom.add_command(run.run_cmd)

nominal/cli/_utils.py

@@ -3,7 +3,7 @@
 import click
 
 from .._config import get_token
-from ..sdk import NominalClient
+from ..core import NominalClient
 
 BASE_URL_OPTION = click.option("--base-url", default="https://api.gov.nominal.io/api")
 TOKEN_OPTION = click.option("--token", help="[default: looked up in ~/.nominal.yml]")

nominal/cli/attachment.py

@@ -8,7 +8,7 @@
 from ._utils import BASE_URL_OPTION, TOKEN_OPTION, get_client
 
 
-@click.group()
+@click.group(name="attachment")
 def attachment_cmd() -> None:
     pass
 

nominal/cli/auth.py

@@ -5,7 +5,7 @@
 from .. import _config
 
 
-@click.group()
+@click.group(name="auth")
 def auth_cmd() -> None:
     pass
 

nominal/cli/dataset.py

@@ -8,7 +8,7 @@
 from ._utils import BASE_URL_OPTION, TOKEN_OPTION, get_client
 
 
-@click.group()
+@click.group(name="dataset")
 def dataset_cmd() -> None:
     pass
 

nominal/cli/run.py

@@ -8,7 +8,7 @@
 from ._utils import BASE_URL_OPTION, TOKEN_OPTION, get_client
 
 
-@click.group()
+@click.group(name="run")
 def run_cmd() -> None:
     pass