github/langchain
1
0
Fork 0
mirror of https://github.com/hwchase17/langchain.git synced 2025-12-02 06:46:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: udpated api reference (#25172)

Browse Source 
- Move the API reference into the vercel build
- Update api reference organization and styling
This commit is contained in:
Bagatur
2024-08-14 07:00:17 -07:00
committed by GitHub
parent 4a812e3193
commit 493e474063
165 changed files with 2333 additions and 4698 deletions
Download Patch File Download Diff File Expand all files Collapse all files

208
docs/api_reference/create_api_rst.py
View File

@@ -239,7 +239,7 @@ def _construct_doc(
package_namespace: str,
members_by_namespace: Dict[str, ModuleMembers],
package_version: str,
) -> str:
) -> List[typing.Tuple[str, str]]:
"""Construct the contents of the reference.rst file for the given package.
Args:
@@ -251,15 +251,38 @@ def _construct_doc(
Returns:
The contents of the reference.rst file.
"""
full_doc = f"""\
=======================
``{package_namespace}`` {package_version}
=======================
docs = []
index_doc = f"""\
:html_theme.sidebar_secondary.remove:
.. currentmodule:: {package_namespace}
.. _{package_namespace}:
======================================
{package_namespace.replace('_', '-')}: {package_version}
======================================
.. automodule:: {package_namespace}
:no-members:
:no-inherited-members:
.. toctree::
:hidden:
:maxdepth: 2
"""
index_autosummary = """
"""
namespaces = sorted(members_by_namespace)
for module in namespaces:
index_doc += f" {module}\n"
module_doc = f"""\
.. currentmodule:: {package_namespace}
.. _{module}:
"""
_members = members_by_namespace[module]
classes = [
el
@@ -281,9 +304,9 @@ def _construct_doc(
]
if not (classes or functions):
continue
section = f":mod:`{package_namespace}.{module}`"
section = f":mod:`{module}`"
underline = "=" * (len(section) + 1)
full_doc += f"""\
module_doc += f"""
{section}
{underline}
@@ -291,12 +314,19 @@ def _construct_doc(
:no-members:
:no-inherited-members:
"""
index_autosummary += f"""
:ref:`{module}`
{'^' * (len(module) + 5)}
.. autosummary::
"""
if classes:
full_doc += f"""\
Classes
--------------
module_doc += f"""\
**Classes**
.. currentmodule:: {package_namespace}
.. autosummary::
@@ -317,19 +347,22 @@ Classes
else:
template = "class.rst"
full_doc += f"""\
module_doc += f"""\
:template: {template}
{class_["qualified_name"]}
"""
index_autosummary += f"""
{class_['qualified_name']}
"""
if functions:
_functions = [f["qualified_name"] for f in functions]
fstring = "\n ".join(sorted(_functions))
full_doc += f"""\
Functions
--------------
module_doc += f"""\
**Functions**
.. currentmodule:: {package_namespace}
.. autosummary::
@@ -340,9 +373,8 @@ Functions
"""
if deprecated_classes:
full_doc += f"""\
Deprecated classes
--------------
module_doc += f"""\
**Deprecated classes**
.. currentmodule:: {package_namespace}
@@ -364,7 +396,7 @@ Deprecated classes
else:
template = "class.rst"
full_doc += f"""\
module_doc += f"""\
:template: {template}
{class_["qualified_name"]}
@@ -374,9 +406,8 @@ Deprecated classes
if deprecated_functions:
_functions = [f["qualified_name"] for f in deprecated_functions]
fstring = "\n ".join(sorted(_functions))
full_doc += f"""\
Deprecated functions
--------------
module_doc += f"""\
**Deprecated functions**
.. currentmodule:: {package_namespace}
@@ -387,7 +418,10 @@ Deprecated functions
{fstring}
"""
return full_doc
docs.append((f"{module}.rst", module_doc))
docs.append(("index.rst", index_doc + index_autosummary))
return docs
def _build_rst_file(package_name: str = "langchain") -> None:
@@ -399,13 +433,14 @@ def _build_rst_file(package_name: str = "langchain") -> None:
package_dir = _package_dir(package_name)
package_members = _load_package_modules(package_dir)
package_version = _get_package_version(package_dir)
with open(_out_file_path(package_name), "w") as f:
f.write(
_doc_first_line(package_name)
+ _construct_doc(
_package_namespace(package_name), package_members, package_version
)
)
output_dir = _out_file_path(package_name)
os.mkdir(output_dir)
rsts = _construct_doc(
_package_namespace(package_name), package_members, package_version
)
for name, rst in rsts:
with open(output_dir / name, "w") as f:
f.write(rst)
def _package_namespace(package_name: str) -> str:
@@ -455,12 +490,117 @@ def _get_package_version(package_dir: Path) -> str:
def _out_file_path(package_name: str) -> Path:
"""Return the path to the file containing the documentation."""
return HERE / f"{package_name.replace('-', '_')}_api_reference.rst"
return HERE / f"{package_name.replace('-', '_')}"
def _doc_first_line(package_name: str) -> str:
"""Return the path to the file containing the documentation."""
return f".. {package_name.replace('-', '_')}_api_reference:\n\n"
def _build_index(dirs: List[str]) -> None:
custom_names = {
"airbyte": "Airbyte",
"aws": "AWS",
"ai21": "AI21",
}
ordered = ["core", "langchain", "text-splitters", "community", "experimental"]
main_ = [dir_ for dir_ in ordered if dir_ in dirs]
integrations = sorted(dir_ for dir_ in dirs if dir_ not in main_)
main_headers = [
" ".join(custom_names.get(x, x.title()) for x in dir_.split("-"))
for dir_ in main_
]
integration_headers = [
" ".join(
custom_names.get(x, x.title().replace("ai", "AI").replace("db", "DB"))
for x in dir_.split("-")
)
for dir_ in integrations
]
main_tree = "\n".join(
f"{header_name}<{dir_.replace('-', '_')}/index>"
for header_name, dir_ in zip(main_headers, main_)
)
main_grid = "\n".join(
f'- header: "**{header_name}**"\n content: "{_package_namespace(dir_).replace("_", "-")}: {_get_package_version(_package_dir(dir_))}"\n link: {dir_.replace("-", "_")}/index.html'
for header_name, dir_ in zip(main_headers, main_)
)
integration_tree = "\n".join(
f"{header_name}<{dir_.replace('-', '_')}/index>"
for header_name, dir_ in zip(integration_headers, integrations)
)
integration_grid = ""
integrations_to_show = [
"openai",
"anthropic",
"google-vertexai",
"aws",
"huggingface",
"mistralai",
]
for header_name, dir_ in sorted(
zip(integration_headers, integrations),
key=lambda h_d: integrations_to_show.index(h_d[1])
if h_d[1] in integrations_to_show
else len(integrations_to_show),
)[: len(integrations_to_show)]:
integration_grid += f'\n- header: "**{header_name}**"\n content: {_package_namespace(dir_).replace("_", "-")} {_get_package_version(_package_dir(dir_))}\n link: {dir_.replace("-", "_")}/index.html'
doc = f"""# LangChain Python API Reference
Welcome to the LangChain Python API reference. This is a reference for all
`langchain-x` packages.
For user guides see [https://python.langchain.com](https://python.langchain.com).
For the legacy API reference hosted on ReadTheDocs see [https://api.python.langchain.com/](https://api.python.langchain.com/).
## Base packages
```{{gallery-grid}}
:grid-columns: "1 2 2 3"
{main_grid}
```
```{{toctree}}
:maxdepth: 2
:hidden:
:caption: Base packages
{main_tree}
```
## Integrations
```{{gallery-grid}}
:grid-columns: "1 2 2 3"
{integration_grid}
```
See the full list of integrations in the Section Navigation.
```{{toctree}}
:maxdepth: 2
:hidden:
:caption: Integrations
{integration_tree}
```
"""
with open(HERE / "reference.md", "w") as f:
f.write(doc)
dummy_index = """\
# API reference
```{toctree}
:maxdepth: 3
:hidden:
Reference<reference>
```
"""
with open(HERE / "index.md", "w") as f:
f.write(dummy_index)
def main(dirs: Optional[list] = None) -> None:
@@ -488,6 +628,8 @@ def main(dirs: Optional[list] = None) -> None:
else:
print("Building package:", dir_)
_build_rst_file(package_name=dir_)
_build_index(dirs)
print("API reference files built.")