From 398a81bc8a31e1d2f11a3f8b398623624ae76e51 Mon Sep 17 00:00:00 2001 From: Matt Carey Date: Tue, 25 Feb 2025 11:15:18 +0000 Subject: [PATCH] fix: docs formatting --- Makefile | 8 +++++ examples/available_tools.py | 2 +- examples/file_uploads.py | 27 +++++++++----- examples/index.py | 38 +++++++++++--------- mkdocs.yml | 70 ++++++++++++++++++------------------- pyproject.toml | 11 +++--- scripts/build_docs.py | 6 ++-- uv.lock | 55 ++++++----------------------- 8 files changed, 104 insertions(+), 113 deletions(-) diff --git a/Makefile b/Makefile index b9aae47..d355a01 100644 --- a/Makefile +++ b/Makefile @@ -19,3 +19,11 @@ test-examples: mypy: uv run mypy stackone_ai + +docs-serve: + uv run scripts/build_docs.py + uv run mkdocs serve + +docs-build: + uv run scripts/build_docs.py + uv run mkdocs build diff --git a/examples/available_tools.py b/examples/available_tools.py index 06c6898..09f103f 100644 --- a/examples/available_tools.py +++ b/examples/available_tools.py @@ -8,7 +8,7 @@ 4. Filtering by specific operations 5. Combining multiple operation patterns -# TODO: experimental - get_available_tools(account_id="your_account_id") +TODO: experimental - get_available_tools(account_id="your_account_id") ```bash uv run examples/available_tools.py diff --git a/examples/file_uploads.py b/examples/file_uploads.py index ba8fd6e..84d35c1 100644 --- a/examples/file_uploads.py +++ b/examples/file_uploads.py @@ -1,6 +1,6 @@ """ -Example demonstrating file upload functionality with StackOne. -Shows how to upload an employee document using the HRIS integration. +Example demonstrating file upload functionality using StackOne. +Shows how to upload an employee document using an HRIS integration. This example is runnable with the following command: ```bash @@ -21,11 +21,13 @@ account_id = "45072196112816593343" employee_id = "c28xIQaWQ6MzM5MzczMDA2NzMzMzkwNzIwNA" +""" +## Resume content -def upload_employee_document() -> None: - """Demonstrate uploading an employee document using StackOne.""" - with tempfile.TemporaryDirectory() as temp_dir: - resume_content = """ +This is a sample resume content that will be uploaded to StackOne. +""" + +resume_content = """ JOHN DOE Software Engineer @@ -38,9 +40,18 @@ def upload_employee_document() -> None: EDUCATION BS Computer Science University of Technology - 2016-2020 - """ + 2016-2020 """ + +""" +## Upload employee document + +This function uploads a resume using the `hris_upload_employee_document` tool. +""" + + +def upload_employee_document() -> None: + with tempfile.TemporaryDirectory() as temp_dir: resume_file = Path(temp_dir) / "resume.pdf" resume_file.write_text(resume_content) diff --git a/examples/index.py b/examples/index.py index b20ea73..4a92dea 100644 --- a/examples/index.py +++ b/examples/index.py @@ -1,32 +1,37 @@ """ -# Getting Started - StackOne AI provides a unified interface for accessing various SaaS tools through AI-friendly APIs. ## Installation ```bash +# Using pip pip install stackone-ai -``` +# Using uv +uv add stackone-ai +``` -## Quick Start +## How to use these docs -Here's a simple example. All examples are complete and runnable. +All examples are complete and runnable. +We use [uv](https://docs.astral.sh/uv/getting-started/installation/) for python dependency management. -You can even run the example directly from the command line: +To run this example, install the dependencies (one-time setup) and run the script: ```bash +uv sync --all-extras uv run examples/index.py ``` -""" -from dotenv import load_dotenv +## Package Usage +""" from stackone_ai import StackOneToolSet """ -## Authenticate with StackOne +## Authentication + +Set the `STACKONE_API_KEY` environment variable: ```bash export STACKONE_API_KEY= @@ -34,6 +39,7 @@ or load from a .env file: """ +from dotenv import load_dotenv load_dotenv() @@ -41,12 +47,12 @@ ## Account IDs StackOne uses account IDs to identify different integrations. -See the example [stackone_account_ids.py](stackone_account_ids.py) for more details. -This example will hardcode the account ID. +See the example [stackone-account-ids.md](stackone-account-ids.md) for more details. + +This example will hardcode the account ID: """ account_id = "45072196112816593343" -employee_id = "c28xIQaWQ6MzM5MzczMDA2NzMzMzkwNzIwNA" def quickstart(): @@ -56,11 +62,11 @@ def quickstart(): tools = toolset.get_tools("hris_*", account_id=account_id) # Use a specific tool - employee_tool = tools.get_tool("hris_get_employee") + employee_tool = tools.get_tool("hris_list_employees") assert employee_tool is not None - employee = employee_tool.execute({"id": employee_id}) - assert employee is not None + employees = employee_tool.execute() + assert employees is not None if __name__ == "__main__": @@ -71,8 +77,8 @@ def quickstart(): Check out some more documentation: -- [Error Handling](error-handling.md) - [StackOne Account IDs](stackone-account-ids.md) +- [Error Handling](error-handling.md) - [Available Tools](available-tools.md) - [File Uploads](file-uploads.md) diff --git a/mkdocs.yml b/mkdocs.yml index 3c5faf7..2ecdebc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,48 +6,46 @@ repo_name: StackOneHQ/stackone-ai-python docs_dir: .docs theme: - name: material - palette: - - media: "(prefers-color-scheme: light)" - scheme: default - primary: black - accent: teal - toggle: - icon: material/brightness-7 - name: Switch to dark mode - - media: "(prefers-color-scheme: dark)" - scheme: slate - primary: teal - accent: black - toggle: - icon: material/brightness-4 - name: Switch to light mode + name: terminal + palette: default features: - - navigation.instant - - navigation.tracking - - navigation.sections - - navigation.expand - - navigation.indexes - - toc.follow - - content.code.copy + - footer.prev_next + - navigation.side.indexes + - navigation.side.toc.hide + - revision.date + - revision.history + - style.links.underline.hide markdown_extensions: - - pymdownx.highlight: - anchor_linenums: true - - pymdownx.inlinehilite - - pymdownx.snippets - - pymdownx.superfences - - admonition - - pymdownx.details - attr_list + - def_list + - footnotes - md_in_html + - meta + - toc: + permalink: "#" + permalink_title: Anchor link to this section for reference + - pymdownx.caret + - pymdownx.mark + - pymdownx.tilde + - pymdownx.snippets: + base_path: + - .docs + - pymdownx.superfences + - pymdownx.highlight: + use_pygments: true + pygments_style: lovelace + noclasses: true + - pymdownx.inlinehilite nav: - Home: index.md - - Examples: - - OpenAI Integration: openai-integration.md - - CrewAI Integration: crewai-integration.md - - LangChain Integration: langchain-integration.md + - Usage: - StackOne Account IDs: stackone-account-ids.md - - Error Handling: error-handling.md - - File Uploads: file-uploads.md + - Error Handling: error-handling.md + - Available Tools: available-tools.md + - File Uploads: file-uploads.md + - Integrations: + - OpenAI: openai-integration.md + - CrewAI: crewai-integration.md + - LangChain: langchain-integration.md diff --git a/pyproject.toml b/pyproject.toml index 1df2d34..e9aa2c5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -36,11 +36,10 @@ examples = [ "python-dotenv>=1.0.1", ] docs = [ - "mkdocs-material>=9.6.4", -] -pymdown-extensions = [ - "mkdocs-material>=9.6.4", -] + "mkdocs-terminal>=4.7.0", + "pygments>=2.12", + "pymdown-extensions" +] [dependency-groups] dev = [ @@ -66,7 +65,7 @@ markers = [ "bin/**.py" = ["T201", "T203"] "scripts/**.py" = ["T201", "T203"] "tests/**.py" = ["T201", "T203"] -"examples/**.py" = ["T201", "T203", "E501", "F841"] +"examples/**.py" = ["T201", "T203", "E501", "F841", "E402"] [tool.ruff] line-length = 110 diff --git a/scripts/build_docs.py b/scripts/build_docs.py index a6163b5..235cee6 100644 --- a/scripts/build_docs.py +++ b/scripts/build_docs.py @@ -17,11 +17,13 @@ def convert_file_to_markdown(py_file: Path) -> str: output = [f"# {title}\n"] # Find all docstrings and their positions - docstring_pattern = r'"""(.*?)"""' + # Match docstrings that start and end on their own lines + docstring_pattern = r'(\n|\A)\s*"""(.*?)"""(\s*\n|\Z)' current_pos = 0 for match in re.finditer(docstring_pattern, content, re.DOTALL): start, end = match.span() + docstring_content = match.group(2).strip() # The actual docstring content is in group 2 # If there's code before this docstring, wrap it if current_pos < start: @@ -32,7 +34,7 @@ def convert_file_to_markdown(py_file: Path) -> str: output.append("```\n") # Add the docstring content as markdown - output.append(match.group(1).strip()) + output.append(docstring_content) current_pos = end # Add any remaining code diff --git a/uv.lock b/uv.lock index 6f6dfdc..df43c2d 100644 --- a/uv.lock +++ b/uv.lock @@ -167,15 +167,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/a6/7d/88054ff3934e7d04c5b3fe67d8158ae3beb7b01621c34640b5f75e7db994/auth0_python-4.8.0-py3-none-any.whl", hash = "sha256:3d3fa18819a98025cc977d4809ad52b14dbe8b73da3ad56d98e4992d3f7e5bbd", size = 134035 }, ] -[[package]] -name = "babel" -version = "2.17.0" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/7d/6b/d52e42361e1aa00709585ecc30b3f9684b3ab62530771402248b1b1d6240/babel-2.17.0.tar.gz", hash = "sha256:0c54cffb19f690cdcc52a3b50bcbf71e07a808d1c80d549f2459b9d2cf0afb9d", size = 9951852 } -wheels = [ - { url = "https://files.pythonhosted.org/packages/b7/b8/3fe70c75fe32afc4bb507f75563d39bc5642255d1d94f1f23604725780bf/babel-2.17.0-py3-none-any.whl", hash = "sha256:4d0b53093fdfb4b21c92b5213dba5a1b23885afa8383709427046b21c366e5f2", size = 10182537 }, -] - [[package]] name = "backoff" version = "2.2.1" @@ -1390,34 +1381,19 @@ wheels = [ ] [[package]] -name = "mkdocs-material" -version = "9.6.4" +name = "mkdocs-terminal" +version = "4.7.0" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "babel" }, - { name = "colorama" }, { name = "jinja2" }, { name = "markdown" }, { name = "mkdocs" }, - { name = "mkdocs-material-extensions" }, - { name = "paginate" }, { name = "pygments" }, { name = "pymdown-extensions" }, - { name = "regex" }, - { name = "requests" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/9b/80/4efbd3df76c6c1ec27130b43662612f9033adc5a4166f1df2acb8dd6fb1b/mkdocs_material-9.6.4.tar.gz", hash = "sha256:4d1d35e1c1d3e15294cb7fa5d02e0abaee70d408f75027dc7be6e30fb32e6867", size = 3942628 } +sdist = { url = "https://files.pythonhosted.org/packages/95/41/0d4ab5fcee2030f4800f0925ccbc03531d44f89686ad07db83cf2fd77854/mkdocs_terminal-4.7.0.tar.gz", hash = "sha256:9a8abcc560d66974a3fcfac9381167c7a3d52add1c30403b8cf35b3d2b10362e", size = 619993 } wheels = [ - { url = "https://files.pythonhosted.org/packages/5b/a5/f3c0e86c1d28fe04f1b724700ff3dd8b3647c89df03a8e10c4bc6b4db1b8/mkdocs_material-9.6.4-py3-none-any.whl", hash = "sha256:414e8376551def6d644b8e6f77226022868532a792eb2c9accf52199009f568f", size = 8688727 }, -] - -[[package]] -name = "mkdocs-material-extensions" -version = "1.3.1" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/79/9b/9b4c96d6593b2a541e1cb8b34899a6d021d208bb357042823d4d2cabdbe7/mkdocs_material_extensions-1.3.1.tar.gz", hash = "sha256:10c9511cea88f568257f960358a467d12b970e1f7b2c0e5fb2bb48cab1928443", size = 11847 } -wheels = [ - { url = "https://files.pythonhosted.org/packages/5b/54/662a4743aa81d9582ee9339d4ffa3c8fd40a4965e033d77b9da9774d3960/mkdocs_material_extensions-1.3.1-py3-none-any.whl", hash = "sha256:adff8b62700b25cb77b53358dad940f3ef973dd6db797907c49e3c2ef3ab4e31", size = 8728 }, + { url = "https://files.pythonhosted.org/packages/1d/98/062d03109576f3dc5a27bb3a2a74bea9b59aa4ed5d2b9b12f98a15a09fd8/mkdocs_terminal-4.7.0-py3-none-any.whl", hash = "sha256:6a223bcef762728f5bcdba045b4acabc3d119ae9215160693f45be8a09889815", size = 641970 }, ] [[package]] @@ -1946,15 +1922,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/88/ef/eb23f262cca3c0c4eb7ab1933c3b1f03d021f2c48f54763065b6f0e321be/packaging-24.2-py3-none-any.whl", hash = "sha256:09abb1bccd265c01f4a3aa3f7a7db064b36514d2cba19a2f694fe6150451a759", size = 65451 }, ] -[[package]] -name = "paginate" -version = "0.5.7" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/ec/46/68dde5b6bc00c1296ec6466ab27dddede6aec9af1b99090e1107091b3b84/paginate-0.5.7.tar.gz", hash = "sha256:22bd083ab41e1a8b4f3690544afb2c60c25e5c9a63a30fa2f483f6c60c8e5945", size = 19252 } -wheels = [ - { url = "https://files.pythonhosted.org/packages/90/96/04b8e52da071d28f5e21a805b19cb9390aa17a47462ac87f5e2696b9566d/paginate-0.5.7-py2.py3-none-any.whl", hash = "sha256:b885e2af73abcf01d9559fd5216b57ef722f8c42affbb63942377668e35c7591", size = 13746 }, -] - [[package]] name = "parso" version = "0.8.4" @@ -2804,7 +2771,9 @@ dependencies = [ [package.optional-dependencies] docs = [ - { name = "mkdocs-material" }, + { name = "mkdocs-terminal" }, + { name = "pygments" }, + { name = "pymdown-extensions" }, ] examples = [ { name = "crewai" }, @@ -2812,9 +2781,6 @@ examples = [ { name = "openai" }, { name = "python-dotenv" }, ] -pymdown-extensions = [ - { name = "mkdocs-material" }, -] [package.dev-dependencies] dev = [ @@ -2834,14 +2800,15 @@ requires-dist = [ { name = "crewai", marker = "extra == 'examples'", specifier = ">=0.102.0" }, { name = "langchain-core", specifier = ">=0.1.0" }, { name = "langchain-openai", marker = "extra == 'examples'", specifier = ">=0.3.6" }, - { name = "mkdocs-material", marker = "extra == 'docs'", specifier = ">=9.6.4" }, - { name = "mkdocs-material", marker = "extra == 'pymdown-extensions'", specifier = ">=9.6.4" }, + { name = "mkdocs-terminal", marker = "extra == 'docs'", specifier = ">=4.7.0" }, { name = "openai", marker = "extra == 'examples'", specifier = ">=1.63.2" }, { name = "pydantic", specifier = ">=2.10.6" }, + { name = "pygments", marker = "extra == 'docs'", specifier = ">=2.12" }, + { name = "pymdown-extensions", marker = "extra == 'docs'" }, { name = "python-dotenv", marker = "extra == 'examples'", specifier = ">=1.0.1" }, { name = "requests", specifier = ">=2.32.3" }, ] -provides-extras = ["examples", "docs", "pymdown-extensions"] +provides-extras = ["examples", "docs"] [package.metadata.requires-dev] dev = [