mirror of
https://github.com/hwchase17/langchain.git
synced 2025-04-28 11:55:21 +00:00
fbd2e10703
## **Description:** The Jupyter notebooks in the docs section are extremely useful and critical for widespread adoption of LangChain amongst new developers. However, because they are also converted to MDX and used to build the HTML for the Docusaurus site, they contain JSX code that degrades readability when opened in a "notebook" setting (local notebook server, google colab, etc.). For instance, here we see the website, with a nice React tab component for installation instructions (`pip` vs `conda`):  Now, here is the same notebook viewed in colab:  Note that the text following "To install LangChain run:" contains snippets of JSX code that is (i) confusing, (ii) bad for readability, (iii) potentially misleading for a novice developer, who might take it literally to mean that "to install LangChain I should run `import Tabs from...`" and then an ill-formed command which mixes the `pip` and `conda` installation instructions. Ideally, we would like to have a system that presents a similar/equivalent UI when viewing the notebooks on the documentation site, or when interacting with them in a notebook setting - or, at a minimum, we should not present ill-formed JSX snippets to someone trying to execute the notebooks. As the documentation itself states, running the notebooks yourself is a great way to learn the tools. Therefore, these distracting and ill-formed snippets are contrary to that goal. ## **Fixes:** * Comment out the JSX code inside the notebook `docs/tutorials/llm_chain` with a special directive `<!-- HIDE_IN_NB` (closed with `HIDE_IN_NB -->`). This makes the JSX code "invisible" when viewed in a notebook setting. * Add a custom preprocessor that runs process_cell and just erases these comment strings. This makes sure they are rendered when converted to MDX. * Minor tweak: Refactor some of the Markdown instructions into an executable codeblock for better experience when running as a notebook. * Minor tweak: Optionally try to get the environment variables from a `.env` file in the repo so the user doesn't have to enter it every time. Depends on the user installing `python-dotenv` and adding their own `.env` file. * Add an environment variable for "LANGSMITH_PROJECT" (default="default"), per the LangSmith docs, so a local user can target a specific project in their LangSmith account. **NOTE:** If this PR is approved, and the maintainers agree with the general goal of aligning the notebook execution experience and the doc site UI, I would plan to implement this on the rest of the JSX snippets that are littered in the notebooks. **NOTE:** I wasn't able to/don't know how to run the linkcheck Makefile commands. - [X] **Lint and test**: Run `make format`, `make lint` and `make test` from the root of the package(s) you've modified. See contribution guidelines for more: https://python.langchain.com/docs/contributing/ --------- Co-authored-by: Really Him <hesereallyhim@proton.me> |
||
|---|---|---|
| .. | ||
| api_reference | ||
| cassettes | ||
| data | ||
| docs | ||
| scripts | ||
| src | ||
| static | ||
| .gitignore | ||
| .yarnrc.yml | ||
| babel.config.js | ||
| docusaurus.config.js | ||
| ignore-step.sh | ||
| Makefile | ||
| package.json | ||
| README.md | ||
| sidebars.js | ||
| vercel_overrides.txt | ||
| vercel_requirements.txt | ||
| vercel.json | ||
| yarn.lock | ||
LangChain Documentation
For more information on contributing to our documentation, see the Documentation Contributing Guide