Metadata-Version: 2.4
Name: mkdocstrings-multirepo
Version: 0.1.0
Summary: Allows for the integration of multiple repos into a single mkdocs instance - no git submodules required.
Author: kay-mw
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Dist: mkdocs>=1.6.0
Requires-Dist: platformdirs>=2.2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# mkdocstrings-multirepo

A simple mkdocs + mkdocstrings plugin that allows you to use docs from multiple
different repos. Simply specify a repo configuration, and those repos become
available to mkdocstrings in one docs build.

## Installation

```bash
uv add mkdocstrings-multirepo
```

**Requirements:** Requires git, [mkdocs](https://www.mkdocs.org/) and
[mkdocstrings](https://mkdocstrings.github.io/) to be installed and configured.

> [!IMPORTANT]
>
> `mkdocstrings-multirepo` must be listed **before** `mkdocstrings` in your
> `plugins` configuration, as it needs to set up repository paths before
> mkdocstrings processes them.

## Features

- **Lean & parallel cloning** - Only fetches the specified ref, and fetches
  multiple repos concurrently for faster builds
- **Reproducibility** - Supports and encourages the use of commit hashes to pin
  specific repo versions
- **Caching** - Repos are cached in your OS cache directory (e.g.
  `~/.cache/mkdocstrings-multirepo` on Linux) and reused between builds
- **Auto-pruning** - Automatically removes unused cached repos when the cache
  grows too large

## Example

```yml
# mkdocs.yml

site_name: mkdocstrings-multirepo

plugins:
  - mkdocstrings-multirepo:
      repos:
        - name: textual
          url: "https://github.com/Textualize/textual.git"
          ref: "501372027f3abc75561881e3803efc34098dabe1"
        - name: rich
          url: "https://github.com/Textualize/rich.git"
          ref: "1d402e0c59f8765e420a5a4440eb2fca7465d1ae"
        - name: pydantic
          url: "https://github.com/pydantic/pydantic.git"
          ref: "08b64f7a43f96f02bb0af8d46aba67b3a68d6e88"
  - mkdocstrings:
```

```md
<!-- A .md file in your docs -->

# Example

<!-- Schema: `::: [name-in-repos-config].path.to.your.module` -->

::: textual.src.textual.cache.LRUCache

::: rich.rich.console.ConsoleDimensions

::: pydantic.pydantic.networks.UrlConstraints
```

![MkDocs + mkdocstrings-multirepo website example](./static/site_example.png)

## Limitations

- **Language support** - `mkdocstrings-multirepo` currently only supports the
  Python parser. Making this language agnostic _seems_ quite simple, so full
  language support may come in the v0.2 release.

## FAQ

### Why does `mkdocstrings-multirepo` notably increase my build times, even when repos are cached?

Including and referencing modules from other repos inherently increases the
strain on `mkdocstrings`. Large repos with deeply nested references may require
[griffe](https://github.com/mkdocstrings/griffe?tab=readme-ov-file) (the
mkdocstrings parser) to recurse a large number of times.

### Why am I getting "Could not collect" errors when trying to document a cloned repo?

This could be for a variety of reasons, such as not using the correct naming
scheme, misspelling a path, etc.

One dubious edge case to be aware of is: if you have a package installed in your
environment (e.g., the `mkdocstrings_multirepo` package itself) and you're also
trying to clone and document a repo with the same `name` in your config, you'll
encounter name collision issues.

You can solve this by either:

1. Removing the repo from your config, and documenting the package directly.
   `mkdocstrings` directly supports documenting packages installed in your
   environment. **(Recommended)**

2. If you _really need_ the package in your `repos` configuration, change the
   name such that it doesn't conflict with the name of any installed packages.
   For example, to clone and document `mkdocstrings-multirepo` when you also
   have `mkdocstrings-multirepo` installed, you could do:

```yml
plugins:
  - mkdocstrings-multirepo:
      repos:
        - name: mkdocstrings_multirepo_repo # Changed to avoid collision
          url: "https://github.com/kay-mw/mkdocstrings-multirepo.git"
          ref: "main"
```

Then reference it as `::: mkdocstrings_multirepo_repo.path.to.some.module`.

### Does this plugin work with [zensical](https://github.com/zensical/zensical)?

Unfortunately not, as this plugin uses the mkdocs plugin API. Zensical doesn't
appear to have a public plugin/module API yet, however I plan to port this
plugin to zensical as soon as that becomes possible.
