feat: docs snippets

[hntrl]

This PR introduces a docs snippets command that statically extracts and lints all code snippets contained within docs to a snippets/ folder.

Motivation

• [langgraph]: please, someone do the simplest thing of putting the js docs into an IDE and seeing all the errors #530
• Allows us to bring language-independent tooling for linting + formatting
• Gives us a hatch to do additional static analysis later down the line

New Commands

• docs snippets will clean, export, and lint all code snippet files
• docs snippets clean will clean all non-boilerplate files from the snippets directories
• docs snippets export will only extract code snippets from docs files
• docs snippets lint will only lint code snippet files already exported to the snippets folder

New code block directives

export

To make this change opt-in, code blocks will only be exported into the snippets folder if it has an export attribute. For instance:

<!-- this will be exported -->
\`\`\`python export
2 + 2
\`\`\`
<!-- this will not be exported -->
\`\`\`python
secret_to_life = 42
\`\`\`

ignore

This directive is only for rendering snippets in the final docs build, and is meant to be used in conjunction with merge-before to give additional scope to the snippet

<!-- this codeblock will not end up in a final build artifact -->
\`\`\`python ignore
print("you wont see me")
\`\`\`

merge-before

You can use this to merge code blocks together into one consistent snippet -- this is helpful for examples that span across multiple code snippets, but still should be treated as one consistent example when we go to export the snippet and lint.

\`\`\`python
foo = "bar"
\`\`\`
\`\`\`python merge-before
print(foo)
\`\`\`

When used with the ignore directive, you can pin additional scopes to the snippet without it being rendered in the final docs build. For instance:

\`\`\`python ignore
from langchain.agents import create_agent
\`\`\`
\`\`\`python merge-before
agent = create_agent(...)
\`\`\`

Structure change: snippets/

This PR adds a top level snippets/ directory that contains each language's boilerplate code for linting + formatting. When docs snippets is run, all code snippets will be exported into each languages directory to be linted and formatted.

Each language directory contains a Makefile that has a lint command that kicks off a linting command for all exported snippets. For python we run the same lint commands as we do in the root of the directory (with some special docs-only rules applied in pyproject.toml, and in JS we run the lint pnpm script which triggers an eslint run.

Each snippet file that gets exported is intentionally not tracked -- we should only really need these snippet files for CI reasons (for now)

Test cases

(might be good as unit tests, but these are just one off checks I've done for now)

• Verify that existing code block rendering is not affected
• Verify that code blocks with the merge-before directive are collapsed into one code snippet
• Verify that code blocks with the ignore directive are omitted from the final build
• Verify that code blocks are only exported to snippets/ if it contains the export directive
• Verify that lints are applied correctly across python and typescript

[github-actions]

Preview ID generated: preview-hunter-1758587405-a9a8fc2