langchain/docs/docs/contributing/documentation/technical_logistics.mdx

# Technical logistics

LangChain documentation consists of two components:

1. Main Documentation: Hosted at [python.langchain.com](https://python.langchain.com/),
this comprehensive resource serves as the primary user-facing documentation.
It covers a wide array of topics, including tutorials, use cases, integrations,
and more, offering extensive guidance on building with LangChain.
The content for this documentation lives in the `/docs` directory of the monorepo.
2. In-code Documentation: This is documentation of the codebase itself, which is also
used to generate the externally facing [API Reference](https://api.python.langchain.com/en/latest/langchain_api_reference.html).
The content for the API reference is autogenerated by scanning the docstrings in the codebase. For this reason we ask that
developers document their code well.

The main documentation is built using [Quarto](https://quarto.org) and [Docusaurus 2](https://docusaurus.io/).

The `API Reference` is largely autogenerated by [sphinx](https://www.sphinx-doc.org/en/master/)
from the code and is hosted by [Read the Docs](https://readthedocs.org/).

We appreciate all contributions to the documentation, whether it be fixing a typo,
adding a new tutorial or example and whether it be in the main documentation or the API Reference.

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.

## 📜 Main Documentation

The content for the main documentation is located in the `/docs` directory of the monorepo.

The documentation is written using a combination of ipython notebooks (`.ipynb` files)
and markdown (`.mdx` files). The notebooks are converted to markdown
using [Quarto](https://quarto.org) and then built using [Docusaurus 2](https://docusaurus.io/).

Feel free to make contributions to the main documentation! 🥰

After modifying the documentation:

1. Run the linting and formatting commands (see below) to ensure that the documentation is well-formatted and free of errors.
2. Optionally build the documentation locally to verify that the changes look good.
3. Make a pull request with the changes.
4. You can preview and verify that the changes are what you wanted by clicking the `View deployment` or `Visit Preview` buttons on the pull request `Conversation` page. This will take you to a preview of the documentation changes.

## ⚒️ Linting and Building Documentation Locally

After writing up the documentation, you may want to lint and build the documentation
locally to ensure that it looks good and is free of errors.

If you're unable to build it locally that's okay as well, as you will be able to
see a preview of the documentation on the pull request page.

### Install dependencies

- [Quarto](https://quarto.org) - package that converts Jupyter notebooks (`.ipynb` files) into mdx files for serving in Docusaurus. [Download link](https://quarto.org/docs/download/).

From the **monorepo root**, run the following command to install the dependencies:

```bash
poetry install --with lint,docs --no-root
````

### Building

The code that builds the documentation is located in the `/docs` directory of the monorepo.

In the following commands, the prefix `api_` indicates that those are operations for the API Reference.

Before building the documentation, it is always a good idea to clean the build directory:

```bash
make docs_clean
make api_docs_clean
```

Next, you can build the documentation as outlined below:

```bash
make docs_build
make api_docs_build
```

Finally, run the link checker to ensure all links are valid:

```bash
make docs_linkcheck
make api_docs_linkcheck
```

### Linting and Formatting

The Main Documentation is linted from the **monorepo root**. To lint the main documentation, run the following from there:

```bash
make lint
```

If you have formatting-related errors, you can fix them automatically with:

```bash
make format
```

## ⌨️ In-code Documentation

The in-code documentation is largely autogenerated by [sphinx](https://www.sphinx-doc.org/en/master/) from the code and is hosted by [Read the Docs](https://readthedocs.org/).

For the API reference to be useful, the codebase must be well-documented. This means that all functions, classes, and methods should have a docstring that explains what they do, what the arguments are, and what the return value is. This is a good practice in general, but it is especially important for LangChain because the API reference is the primary resource for developers to understand how to use the codebase.

We generally follow the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) for docstrings.

Here is an example of a well-documented function:

```python

def my_function(arg1: int, arg2: str) -> float:
    """This is a short description of the function. (It should be a single sentence.)

    This is a longer description of the function. It should explain what
    the function does, what the arguments are, and what the return value is.
    It should wrap at 88 characters.

    Examples:
        This is a section for examples of how to use the function.

        .. code-block:: python

            my_function(1, "hello")

    Args:
        arg1: This is a description of arg1. We do not need to specify the type since
            it is already specified in the function signature.
        arg2: This is a description of arg2.

    Returns:
        This is a description of the return value.
    """
    return 3.14
```

### Linting and Formatting

The in-code documentation is linted from the directories belonging to the packages
being documented.

For example, if you're working on the `langchain-community` package, you would change
the working directory to the `langchain-community` directory:

```bash
cd [root]/libs/langchain-community
```

Set up a virtual environment for the package if you haven't done so already.

Install the dependencies for the package.

```bash
poetry install --with lint
```

Then you can run the following commands to lint and format the in-code documentation:

```bash
make format
make lint
```

## Verify Documentation Changes

After pushing documentation changes to the repository, you can preview and verify that the changes are
what you wanted by clicking the `View deployment` or `Visit Preview` buttons on the pull request `Conversation` page.
This will take you to a preview of the documentation changes.
This preview is created by [Vercel](https://vercel.com/docs/getting-started-with-vercel).