From 4bc190d87d87e053b4d88eb0f09159f392191126 Mon Sep 17 00:00:00 2001 From: Bagatur Date: Mon, 25 Nov 2024 15:34:05 -0800 Subject: [PATCH 01/10] python,docs: revamp python api reference --- python/Makefile | 10 +++ python/docs/create_api_rst.py | 81 +++++++++++++++++++++---- python/docs/requirements.txt | 1 + python/docs/scripts/custom_formatter.py | 4 +- python/docs/templates/class.rst | 36 +++++++++++ python/docs/templates/function.rst | 8 +++ python/langsmith/evaluation/_runner.py | 2 +- 7 files changed, 127 insertions(+), 15 deletions(-) create mode 100644 python/docs/templates/class.rst create mode 100644 python/docs/templates/function.rst diff --git a/python/Makefile b/python/Makefile index f7ca1f502..41f1bf4a6 100644 --- a/python/Makefile +++ b/python/Makefile @@ -62,3 +62,13 @@ build: publish: poetry publish --dry-run + +api_docs_build: + poetry run python docs/create_api_rst.py + cd docs && poetry run make html + poetry run python docs/scripts/custom_formatter.py docs/_build/html/ + cp docs/_build/html/{reference,index}.html + open docs/_build/html/index.html + +api_docs_clean: + git clean -fd ./docs/ diff --git a/python/docs/create_api_rst.py b/python/docs/create_api_rst.py index 253352767..fcb88cade 100644 --- a/python/docs/create_api_rst.py +++ b/python/docs/create_api_rst.py @@ -108,18 +108,18 @@ def _load_module_members(module_path: str, namespace: str) -> ModuleMembers: else "Pydantic" if issubclass(type_, BaseModel) else "Regular" ) ) - if hasattr(type_, "__slots__"): - for func_name, func_type in inspect.getmembers(type_): - if inspect.isfunction(func_type): - functions.append( - FunctionInfo( - name=func_name, - qualified_name=f"{namespace}.{name}.{func_name}", - is_public=not func_name.startswith("_"), - is_deprecated=".. deprecated::" - in (func_type.__doc__ or ""), - ) - ) + # if hasattr(type_, "__slots__"): + # for func_name, func_type in inspect.getmembers(type_): + # if inspect.isfunction(func_type): + # functions.append( + # FunctionInfo( + # name=func_name, + # qualified_name=f"{namespace}.{name}.{func_name}", + # is_public=not func_name.startswith("_"), + # is_deprecated=".. deprecated::" + # in (func_type.__doc__ or ""), + # ) + # ) classes_.append( ClassInfo( name=name, @@ -158,6 +158,7 @@ def _load_package_modules( "_arunner.py", "_testing.py", "_expect.py", + "_openai.py", }: continue @@ -198,6 +199,7 @@ def _load_package_modules( "schemas", "utils", "anonymizer", + "wrappers" ] @@ -355,7 +357,7 @@ def _priority(mod: str): """ docs.append((f"{module}.rst", module_doc)) - docs.append(("index.rst", index_doc)) + # docs.append(("index.rst", index_doc)) return docs @@ -369,6 +371,58 @@ def _get_package_version(package_dir: Path) -> str: sys.exit(1) +def _build_index() -> None: + doc = """# LangSmith Python SDK API Reference + +Welcome to the API reference for the LangSmith Python SDK. + +For user guides see [https://docs.smith.langchain.com](https://docs.smith.langchain.com). +""" + + doc += f""" + +```{{toctree}} +:maxdepth: 2 +:hidden: + + client + async_client + evaluation + run_helpers + wrappers + _testing<_testing> +``` + +#### Key classes and functions + +| Class/function | Description | +| :- | :- | +| [Client](client/langsmith.client.Client) | Synchronous client for interacting with the LangSmith API. | +| [AsyncClient](async_client/langsmith.async_client.AsyncClient) | Asynchronous client for interacting with the LangSmith API. | +| [traceable](run_helpers/langsmith.run_helpers.traceable) | Wrapper/decorator for tracing any function. | +| [wrap_openai](wrappers/langsmith.wrappers._openai.wrap_openai) | Wrapper for OpenAI client, adds LangSmith tracing to all OpenAI calls. | +| [evaluate](evaluation/langsmith.evaluation._runner.evaluate) | Evaluate an application on a dataset. | +| [aevaluate](evaluation/langsmith.evaluation._arunner.aevaluate) | Asynchronously evaluate an application on a dataset. | +| [unit](_testing/langsmith._testing.unit) | Create a unit test. | + +""" + + with open(HERE / "reference.md", "w") as f: + f.write(doc) + + dummy_index = """\ +# API reference + +```{toctree} +:maxdepth: 3 +:hidden: + +Reference +``` +""" + with open(HERE / "index.md", "w") as f: + f.write(dummy_index) + def main() -> None: print("Starting to build API reference files.") package_members = _load_package_modules(PACKAGE_DIR) @@ -377,6 +431,7 @@ def main() -> None: for name, rst in rsts: with open(HERE / name, "w") as f: f.write(rst) + _build_index() print("API reference files built.") diff --git a/python/docs/requirements.txt b/python/docs/requirements.txt index c93e13128..cfdcda8c3 100644 --- a/python/docs/requirements.txt +++ b/python/docs/requirements.txt @@ -9,4 +9,5 @@ pyyaml sphinx-design sphinx-copybutton beautifulsoup4 +openai -e python diff --git a/python/docs/scripts/custom_formatter.py b/python/docs/scripts/custom_formatter.py index ba85484e9..131a55cdf 100644 --- a/python/docs/scripts/custom_formatter.py +++ b/python/docs/scripts/custom_formatter.py @@ -17,7 +17,9 @@ def process_toc_h3_elements(html_content: str) -> str: # Process each element for element in toc_h3_elements: - element = element.a.code.span + if element.a.code: + element = element.a.code.span + # Get the text content of the element content = element.get_text() diff --git a/python/docs/templates/class.rst b/python/docs/templates/class.rst new file mode 100644 index 000000000..b023d7733 --- /dev/null +++ b/python/docs/templates/class.rst @@ -0,0 +1,36 @@ +{{ objname }} +{{ underline }}============== + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Attributes') }} + + .. autosummary:: + {% for item in attributes %} + ~{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block methods %} + {% if methods %} + .. rubric:: {{ _('Methods') }} + + .. autosummary:: + {% for item in methods %} + ~{{ item }} + {%- endfor %} + + {% for item in methods %} + .. automethod:: {{ item }} + {%- endfor %} + + {% endif %} + {% endblock %} + + +.. example_links:: {{ objname }} diff --git a/python/docs/templates/function.rst b/python/docs/templates/function.rst new file mode 100644 index 000000000..52e0bb6b3 --- /dev/null +++ b/python/docs/templates/function.rst @@ -0,0 +1,8 @@ +{{ objname }} +{{ underline }}============== + +.. currentmodule:: {{ module }} + +.. autofunction:: {{ objname }} + +.. example_links:: {{ objname }} \ No newline at end of file diff --git a/python/langsmith/evaluation/_runner.py b/python/langsmith/evaluation/_runner.py index f4e2076ec..b4dddb653 100644 --- a/python/langsmith/evaluation/_runner.py +++ b/python/langsmith/evaluation/_runner.py @@ -106,7 +106,7 @@ def evaluate( experiment: Optional[Union[schemas.TracerSession, str, uuid.UUID]] = None, upload_results: bool = True, ) -> ExperimentResults: - r"""Evaluate a target system or function on a given dataset. + r"""Evaluate an application on a given dataset. Args: target (TARGET_T): The target system or function to evaluate. From 22eceffb8074f8155b45fc550a31c2c5417718e9 Mon Sep 17 00:00:00 2001 From: Bagatur Date: Mon, 25 Nov 2024 15:36:45 -0800 Subject: [PATCH 02/10] build --- .readthedocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.readthedocs.yml b/.readthedocs.yml index 98b654db8..bdc60e728 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -20,6 +20,7 @@ build: - . .venv/bin/activate - uv pip install -r python/docs/requirements.txt - . .venv/bin/activate && cd python/docs && make clobber generate-api-rst html && cd ../.. + - cp python/docs/_build/html/{reference,index}.html - cp -r python/docs/_build/html $READTHEDOCS_OUTPUT # Build documentation in the docs/ directory with Sphinx sphinx: From d7744aa32c667cae86d18b83a35baabc88484381 Mon Sep 17 00:00:00 2001 From: Bagatur Date: Mon, 25 Nov 2024 15:44:44 -0800 Subject: [PATCH 03/10] fmt --- python/docs/create_api_rst.py | 7 ++++--- python/pyproject.toml | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/python/docs/create_api_rst.py b/python/docs/create_api_rst.py index fcb88cade..1b8321113 100644 --- a/python/docs/create_api_rst.py +++ b/python/docs/create_api_rst.py @@ -199,7 +199,7 @@ def _load_package_modules( "schemas", "utils", "anonymizer", - "wrappers" + "wrappers", ] @@ -379,9 +379,9 @@ def _build_index() -> None: For user guides see [https://docs.smith.langchain.com](https://docs.smith.langchain.com). """ - doc += f""" + doc += """ -```{{toctree}} +```{toctree} :maxdepth: 2 :hidden: @@ -423,6 +423,7 @@ def _build_index() -> None: with open(HERE / "index.md", "w") as f: f.write(dummy_index) + def main() -> None: print("Starting to build API reference files.") package_members = _load_package_modules(PACKAGE_DIR) diff --git a/python/pyproject.toml b/python/pyproject.toml index 51dfb7e3f..7f5e4c369 100644 --- a/python/pyproject.toml +++ b/python/pyproject.toml @@ -99,7 +99,7 @@ convention = "google" "langsmith/run_helpers.py" = ["E501"] "docs/conf.py" = ["E501"] "langsmith/cli/*" = ["T201", "D", "UP"] -"docs/create_api_rst.py" = ["D101", "D103"] +"docs/create_api_rst.py" = ["D101", "D103", "E501"] "docs/scripts/custom_formatter.py" = ["D100"] "langsmith/anonymizer.py" = ["E501"] "langsmith/async_client.py" = ["E501"] From ce3d8ae2cf616069d1ee310e8342f1f839f1ba35 Mon Sep 17 00:00:00 2001 From: Bagatur Date: Mon, 25 Nov 2024 15:45:34 -0800 Subject: [PATCH 04/10] fix --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index bdc60e728..e0290c2c4 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -20,7 +20,7 @@ build: - . .venv/bin/activate - uv pip install -r python/docs/requirements.txt - . .venv/bin/activate && cd python/docs && make clobber generate-api-rst html && cd ../.. - - cp python/docs/_build/html/{reference,index}.html + - cp python/docs/_build/html/reference.html python/docs/_build/html/index.html - cp -r python/docs/_build/html $READTHEDOCS_OUTPUT # Build documentation in the docs/ directory with Sphinx sphinx: From bb2efa242a9cb92ceb31f4f4a58c4ff16110e75b Mon Sep 17 00:00:00 2001 From: Bagatur Date: Mon, 25 Nov 2024 16:07:40 -0800 Subject: [PATCH 05/10] nit --- python/docs/create_api_rst.py | 34 ++++++++++++++++------------------ 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/python/docs/create_api_rst.py b/python/docs/create_api_rst.py index 1b8321113..2be0a1525 100644 --- a/python/docs/create_api_rst.py +++ b/python/docs/create_api_rst.py @@ -371,17 +371,27 @@ def _get_package_version(package_dir: Path) -> str: sys.exit(1) -def _build_index() -> None: - doc = """# LangSmith Python SDK API Reference +def _build_index(package_version: str) -> None: + doc = f"""# LangSmith Python SDK +**Version: `{package_version}`** Welcome to the API reference for the LangSmith Python SDK. For user guides see [https://docs.smith.langchain.com](https://docs.smith.langchain.com). -""" - doc += """ +Here are quick links to some of the key classes and functions: -```{toctree} +| Class/function | Description | +| :- | :- | +| [Client](client/langsmith.client.Client) | Synchronous client for interacting with the LangSmith API. | +| [AsyncClient](async_client/langsmith.async_client.AsyncClient) | Asynchronous client for interacting with the LangSmith API. | +| [traceable](run_helpers/langsmith.run_helpers.traceable) | Wrapper/decorator for tracing any function. | +| [wrap_openai](wrappers/langsmith.wrappers._openai.wrap_openai) | Wrapper for OpenAI client, adds LangSmith tracing to all OpenAI calls. | +| [evaluate](evaluation/langsmith.evaluation._runner.evaluate) | Evaluate an application on a dataset. | +| [aevaluate](evaluation/langsmith.evaluation._arunner.aevaluate) | Asynchronously evaluate an application on a dataset. | +| [unit](_testing/langsmith._testing.unit) | Create a LangSmith unit test. | + +```{{toctree}} :maxdepth: 2 :hidden: @@ -393,18 +403,6 @@ def _build_index() -> None: _testing<_testing> ``` -#### Key classes and functions - -| Class/function | Description | -| :- | :- | -| [Client](client/langsmith.client.Client) | Synchronous client for interacting with the LangSmith API. | -| [AsyncClient](async_client/langsmith.async_client.AsyncClient) | Asynchronous client for interacting with the LangSmith API. | -| [traceable](run_helpers/langsmith.run_helpers.traceable) | Wrapper/decorator for tracing any function. | -| [wrap_openai](wrappers/langsmith.wrappers._openai.wrap_openai) | Wrapper for OpenAI client, adds LangSmith tracing to all OpenAI calls. | -| [evaluate](evaluation/langsmith.evaluation._runner.evaluate) | Evaluate an application on a dataset. | -| [aevaluate](evaluation/langsmith.evaluation._arunner.aevaluate) | Asynchronously evaluate an application on a dataset. | -| [unit](_testing/langsmith._testing.unit) | Create a unit test. | - """ with open(HERE / "reference.md", "w") as f: @@ -432,7 +430,7 @@ def main() -> None: for name, rst in rsts: with open(HERE / name, "w") as f: f.write(rst) - _build_index() + _build_index(package_version) print("API reference files built.") From 4951395ecc2ce6d887593b4f1794c834b1aed43e Mon Sep 17 00:00:00 2001 From: Bagatur Date: Mon, 25 Nov 2024 16:10:22 -0800 Subject: [PATCH 06/10] wordmark --- python/docs/_static/wordmark-api-dark.svg | 15 ++++++++++----- python/docs/_static/wordmark-api.svg | 17 +++++++++++------ 2 files changed, 21 insertions(+), 11 deletions(-) diff --git a/python/docs/_static/wordmark-api-dark.svg b/python/docs/_static/wordmark-api-dark.svg index c33ec9253..6d0aeb837 100644 --- a/python/docs/_static/wordmark-api-dark.svg +++ b/python/docs/_static/wordmark-api-dark.svg @@ -1,11 +1,16 @@ - - - + + + + + - - + + + + + diff --git a/python/docs/_static/wordmark-api.svg b/python/docs/_static/wordmark-api.svg index a9f8f59db..12fafae98 100644 --- a/python/docs/_static/wordmark-api.svg +++ b/python/docs/_static/wordmark-api.svg @@ -1,11 +1,16 @@ - - - - + + + + + + - - + + + + + From 5091d79932dcedb81100b00558c0f96458575cc5 Mon Sep 17 00:00:00 2001 From: Bagatur Date: Mon, 25 Nov 2024 16:14:06 -0800 Subject: [PATCH 07/10] fix types --- python/docs/templates/enum.rst | 14 ++++++++++++++ python/docs/templates/pydantic.rst | 24 ++++++++++++++++++++++++ python/docs/templates/typeddict.rst | 14 ++++++++++++++ 3 files changed, 52 insertions(+) create mode 100644 python/docs/templates/enum.rst create mode 100644 python/docs/templates/pydantic.rst create mode 100644 python/docs/templates/typeddict.rst diff --git a/python/docs/templates/enum.rst b/python/docs/templates/enum.rst new file mode 100644 index 000000000..e53feddac --- /dev/null +++ b/python/docs/templates/enum.rst @@ -0,0 +1,14 @@ +{{ objname }} +{{ underline }}============== + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + + {% block attributes %} + {% for item in attributes %} + .. autoattribute:: {{ item }} + {% endfor %} + {% endblock %} + +.. example_links:: {{ objname }} diff --git a/python/docs/templates/pydantic.rst b/python/docs/templates/pydantic.rst new file mode 100644 index 000000000..63ccf6765 --- /dev/null +++ b/python/docs/templates/pydantic.rst @@ -0,0 +1,24 @@ +{{ objname }} +{{ underline }}============== + +.. currentmodule:: {{ module }} + +.. autopydantic_model:: {{ objname }} + :model-show-json: False + :model-show-config-summary: False + :model-show-validator-members: False + :model-show-field-summary: False + :field-signature-prefix: param + :members: + :undoc-members: + :inherited-members: + :member-order: groupwise + :show-inheritance: True + :special-members: __call__ + :exclude-members: construct, copy, dict, from_orm, parse_file, parse_obj, parse_raw, schema, schema_json, update_forward_refs, validate, json, is_lc_serializable, to_json, to_json_not_implemented, lc_secrets, lc_attributes, lc_id, get_lc_namespace, model_construct, model_copy, model_dump, model_dump_json, model_parametrized_name, model_post_init, model_rebuild, model_validate, model_validate_json, model_validate_strings, model_extra, model_fields_set, model_json_schema + + + {% block attributes %} + {% endblock %} + +.. example_links:: {{ objname }} diff --git a/python/docs/templates/typeddict.rst b/python/docs/templates/typeddict.rst new file mode 100644 index 000000000..4cf3ce01e --- /dev/null +++ b/python/docs/templates/typeddict.rst @@ -0,0 +1,14 @@ +{{ objname }} +{{ underline }}============== + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + + {% block attributes %} + {% for item in attributes %} + .. autoattribute:: {{ item }} + {% endfor %} + {% endblock %} + +.. example_links:: {{ objname }} From 67a483fadad4377faea9a9a4e2d3d5e9ab2c2f52 Mon Sep 17 00:00:00 2001 From: Bagatur Date: Tue, 26 Nov 2024 13:03:18 -0800 Subject: [PATCH 08/10] sidenav title --- python/docs/conf.py | 2 ++ python/docs/templates/sidebar-nav-bs.html | 16 ++++++++++++++++ 2 files changed, 18 insertions(+) create mode 100644 python/docs/templates/sidebar-nav-bs.html diff --git a/python/docs/conf.py b/python/docs/conf.py index dae18242c..38b2ae558 100644 --- a/python/docs/conf.py +++ b/python/docs/conf.py @@ -222,6 +222,7 @@ def setup(app): ], "icon_links_label": "Quick Links", "external_links": [], + "sidebar_primary_title": "Your Custom Title Here", } @@ -259,3 +260,4 @@ def setup(app): html_context["READTHEDOCS"] = True master_doc = "index" +templates_path=['templates'] \ No newline at end of file diff --git a/python/docs/templates/sidebar-nav-bs.html b/python/docs/templates/sidebar-nav-bs.html new file mode 100644 index 000000000..4734f1144 --- /dev/null +++ b/python/docs/templates/sidebar-nav-bs.html @@ -0,0 +1,16 @@ +{# Displays the TOC-subtree for pages nested under the currently active top-level TOCtree element. #} +

{{ _("Modules") }}

+
+ {{- generate_toctree_html( + "sidebar", + show_nav_level=theme_show_nav_level | int, + maxdepth=theme_navigation_depth | int, + collapse=theme_collapse_navigation | tobool, + includehidden=theme_sidebar_includehidden | tobool, + titles_only=True + ) + -}} +
+ \ No newline at end of file From 8a8e0f272f593e4810f4203eb5c3f513e289d642 Mon Sep 17 00:00:00 2001 From: Bagatur Date: Tue, 26 Nov 2024 18:17:11 -0800 Subject: [PATCH 09/10] comment --- python/docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/python/docs/conf.py b/python/docs/conf.py index 38b2ae558..caba005dd 100644 --- a/python/docs/conf.py +++ b/python/docs/conf.py @@ -110,7 +110,7 @@ def setup(app): "sphinx.ext.napoleon", "sphinx.ext.viewcode", "sphinxcontrib.autodoc_pydantic", - "IPython.sphinxext.ipython_console_highlighting", + # "IPython.sphinxext.ipython_console_highlighting", "myst_parser", "_extensions.gallery_directive", "sphinx_design", From 6fd3aefd177cf530c05f7754c851b3df8d45bebd Mon Sep 17 00:00:00 2001 From: Bagatur Date: Wed, 27 Nov 2024 12:59:35 -0800 Subject: [PATCH 10/10] fmt --- python/docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/python/docs/conf.py b/python/docs/conf.py index caba005dd..abcb304a2 100644 --- a/python/docs/conf.py +++ b/python/docs/conf.py @@ -260,4 +260,4 @@ def setup(app): html_context["READTHEDOCS"] = True master_doc = "index" -templates_path=['templates'] \ No newline at end of file +templates_path = ["templates"]