Feature: linkcheck-action (langchain-ai#534) (langchain-ai#542)

- Add support for local build and linkchecking of docs
- Add GitHub Action to automatically check links before prior to
publication
- Minor reformat of Contributing readme
- Fix existing broken links

Co-authored-by: Hunter Gerlach <[email protected]>

Co-authored-by: Hunter Gerlach <[email protected]>
Co-authored-by: Hunter Gerlach <[email protected]>

.github/workflows/linkcheck.yml

@@ -0,0 +1,36 @@
+name: linkcheck
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+env:
+  POETRY_VERSION: "1.3.1"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.11"
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install poetry
+        run: |
+          pipx install poetry==$POETRY_VERSION
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: poetry
+      - name: Install dependencies
+        run: |
+          poetry install --with docs
+      - name: Build the docs
+        run: |
+          make docs_build
+      - name: Analyzing the docs with linkcheck
+        run: |
+          make docs_linkcheck

.gitignore

@@ -107,6 +107,7 @@ celerybeat.pid
 # Environments
 .env
 .venv
+.venvs
 env/
 venv/
 ENV/

CONTRIBUTING.md

@@ -55,9 +55,7 @@ even patch releases may contain [non-backwards-compatible changes](https://semve
 If your contribution has made its way into a release, we will want to give you credit on Twitter (only if you want though)!
 If you have a Twitter account you would like us to mention, please let us know in the PR or in another manner.
 
-## 🤖Developer Setup
-
-### 🚀Quick Start
+## 🚀Quick Start
 
 This project uses [Poetry](https://python-poetry.org/) as a dependency manager. Check out Poetry's [documentation on how to install it](https://python-poetry.org/docs/#installation) on your system before proceeding.
 
@@ -77,9 +75,9 @@ This will install all requirements for running the package, examples, linting, f
 
 Now, you should be able to run the common tasks in the following section.
 
-### ✅Common Tasks
+## ✅Common Tasks
 
-#### Code Formatting
+### Code Formatting
 
 Formatting for this project is done via a combination of [Black](https://black.readthedocs.io/en/stable/) and [isort](https://pycqa.github.io/isort/).
 
@@ -89,7 +87,7 @@ To run formatting for this project:
 make format
 ```
 
-#### Linting
+### Linting
 
 Linting for this project is done via a combination of [Black](https://black.readthedocs.io/en/stable/), [isort](https://pycqa.github.io/isort/), [flake8](https://flake8.pycqa.org/en/latest/), and [mypy](http://mypy-lang.org/).
 
@@ -101,7 +99,7 @@ make lint
 
 We recognize linting can be annoying - if you do not want to do it, please contact a project maintainer, and they can help you with it. We do not want this to be a blocker for good code getting contributed.
 
-#### Coverage
+### Coverage
 
 Code coverage (i.e. the amount of code that is covered by unit tests) helps identify areas of the code that are potentially more or less brittle.
 
@@ -111,7 +109,7 @@ To get a report of current coverage, run the following:
 make coverage
 ```
 
-#### Testing
+### Testing
 
 Unit tests cover modular logic that does not require calls to outside APIs.
 
@@ -133,7 +131,7 @@ make integration_tests
 
 If you add support for a new external API, please add a new integration test.
 
-#### Adding a Jupyter Notebook
+### Adding a Jupyter Notebook
 
 If you are adding a Jupyter notebook example, you'll want to install the optional `dev` dependencies.
 
@@ -151,10 +149,32 @@ poetry run jupyter notebook
 
 When you run `poetry install`, the `langchain` package is installed as editable in the virtualenv, so your new logic can be imported into the notebook.
 
-#### Contribute Documentation
+## Documentation
+
+### Contribute Documentation
 
 Docs are largely autogenerated by [sphinx](https://www.sphinx-doc.org/en/master/) from the code.
 
 For that reason, we ask that you add good documentation to all classes and methods.
 
 Similar to linting, we recognize documentation can be annoying. If you do not want to do it, please contact a project maintainer, and they can help you with it. We do not want this to be a blocker for good code getting contributed.
+
+### Build Documentation Locally
+
+Before building the documentation, it is always a good idea to clean the build directory:
+
+```bash
+make docs_clean
+```
+
+Next, you can run the linkchecker to make sure all links are valid:
+
+```bash
+make docs_linkcheck
+```
+
+Finally, you can build the documentation as outlined below:
+
+```bash
+make docs_build
+```

Makefile

@@ -6,6 +6,15 @@ coverage:
 		--cov-report xml \
 		--cov-report term-missing:skip-covered
 
+docs_build:
+	cd docs && poetry run make html
+
+docs_clean:
+	cd docs && poetry run make clean
+
+docs_linkcheck:
+	poetry run linkchecker docs/_build/html/index.html
+
 format:
 	poetry run black .
 	poetry run isort .

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= 
 SPHINXBUILD   ?= sphinx-build
 SPHINXAUTOBUILD   ?= sphinx-autobuild
 SOURCEDIR     = .

docs/conf.py

@@ -48,8 +48,7 @@
     "sphinx_panels",
     "IPython.sphinxext.ipython_console_highlighting",
 ]
-source_suffix = [".rst", ".md"]
-
+source_suffix = [".ipynb", ".html", ".md", ".rst"]
 
 autodoc_pydantic_model_show_json = False
 autodoc_pydantic_field_list_validators = False

docs/glossary.md

@@ -1,81 +1,90 @@
 # Glossary
 
 This is a collection of terminology commonly used when developing LLM applications.
-It contains reference to external papers or sources where the concept was first introduced, 
+It contains reference to external papers or sources where the concept was first introduced,
 as well as to places in LangChain where the concept is used.
 
 ## Chain of Thought Prompting
 
-A prompting technique used to encourage the model to generate a series of intermediate reasoning steps. 
+A prompting technique used to encourage the model to generate a series of intermediate reasoning steps.
 A less formal way to induce this behavior is to include “Let’s think step-by-step” in the prompt.
 
 Resources:
+
 - [Chain-of-Thought Paper](https://arxiv.org/pdf/2201.11903.pdf)
 - [Step-by-Step Paper](https://arxiv.org/abs/2112.00114)
 
 ## Action Plan Generation
 
-A prompt usage that uses a language model to generate actions to take. 
+A prompt usage that uses a language model to generate actions to take.
 The results of these actions can then be fed back into the language model to generate a subsequent action.
 
 Resources:
+
 - [WebGPT Paper](https://arxiv.org/pdf/2112.09332.pdf)
 - [SayCan Paper](https://say-can.github.io/assets/palm_saycan.pdf)
 
 ## ReAct Prompting
 
-A prompting technique that combines Chain-of-Thought prompting with action plan generation. 
-This induces the to model to think about what action to take, then take it. 
+A prompting technique that combines Chain-of-Thought prompting with action plan generation.
+This induces the to model to think about what action to take, then take it.
 
 Resources:
+
 - [Paper](https://arxiv.org/pdf/2210.03629.pdf)
-- [LangChain Example](https://github.com/hwchase17/langchain/blob/master/docs/examples/agents/react.ipynb)
+- [LangChain Example](./modules/agents/implementations/react.ipynb)
 
 ## Self-ask
 
-A prompting method that builds on top of chain-of-thought prompting. 
-In this method, the model explicitly asks itself follow-up questions, which are then answered by an external search engine. 
+A prompting method that builds on top of chain-of-thought prompting.
+In this method, the model explicitly asks itself follow-up questions, which are then answered by an external search engine.
 
 Resources:
+
 - [Paper](https://ofir.io/self-ask.pdf)
-- [LangChain Example](https://github.com/hwchase17/langchain/blob/master/docs/examples/agents/self_ask_with_search.ipynb)
+- [LangChain Example](./modules/agents/implementations/self_ask_with_search.ipynb)
 
 ## Prompt Chaining
 
-Combining multiple LLM calls together, with the output of one-step being the input to the next. 
+Combining multiple LLM calls together, with the output of one-step being the input to the next.
+
+Resources:
 
-Resources: 
 - [PromptChainer Paper](https://arxiv.org/pdf/2203.06566.pdf)
 - [Language Model Cascades](https://arxiv.org/abs/2207.10342)
 - [ICE Primer Book](https://primer.ought.org/)
 - [Socratic Models](https://socraticmodels.github.io/)
 
 ## Memetic Proxy
 
-Encouraging the LLM to respond in a certain way framing the discussion in a context that the model knows of and that will result in that type of response. For example, as a conversation between a student and a teacher. 
+Encouraging the LLM to respond in a certain way framing the discussion in a context that the model knows of and that will result in that type of response. For example, as a conversation between a student and a teacher.
 
 Resources:
+
 - [Paper](https://arxiv.org/pdf/2102.07350.pdf)
 
 ## Self Consistency
 
-A decoding strategy that samples a diverse set of reasoning paths and then selects the most consistent answer. 
-Is most effective when combined with Chain-of-thought prompting. 
+A decoding strategy that samples a diverse set of reasoning paths and then selects the most consistent answer.
+Is most effective when combined with Chain-of-thought prompting.
 
 Resources:
+
 - [Paper](https://arxiv.org/pdf/2203.11171.pdf)
 
 ## Inception
 
-Also called “First Person Instruction”. 
-Encouraging the model to think a certain way by including the start of the model’s response in the prompt. 
+Also called “First Person Instruction”.
+Encouraging the model to think a certain way by including the start of the model’s response in the prompt.
 
 Resources:
+
 - [Example](https://twitter.com/goodside/status/1583262455207460865?s=20&t=8Hz7XBnK1OF8siQrxxCIGQ)
 
 ## MemPrompt
 
 MemPrompt maintains a memory of errors and user feedback, and uses them to prevent repetition of mistakes.
 
 Resources:
+
 - [Paper](https://memprompt.com/)