mkdocs-multirepo-plugin


Namemkdocs-multirepo-plugin JSON
Version 0.7.0 PyPI version JSON
download
home_pagehttps://pypi.org/project/mkdocs-multirepo-plugin/
SummaryBuild documentation in multiple repos into one site.
upload_time2024-01-19 13:45:50
maintainer
docs_urlNone
authorjdoiro3
requires_python
licenseMIT
keywords mkdocs docs documentation
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            If you like this plugin and want me to continue maintaining it in my free time, please buy me a [beer 🍺](https://www.buymeacoffee.com/jdoiro) or sponser this plugin!

# mkdocs-multirepo-plugin

[![](https://github.com/jdoiro3/mkdocs-multirepo-plugin/workflows/Tests/badge.svg)](https://github.com/jdoiro3/mkdocs-multirepo-plugin/actions)
[![](https://github.com/jdoiro3/mkdocs-multirepo-plugin/workflows/Build%2C%20Test%20%26%20Deploy/badge.svg)](https://github.com/jdoiro3/mkdocs-multirepo-plugin/actions)
[![PyPI](https://img.shields.io/pypi/v/mkdocs-multirepo-plugin)](https://pypi.org/project/mkdocs-multirepo-plugin/)
[![Project Status: Inactive – The project has reached a stable, usable state but is no longer being actively developed; support/maintenance will be provided as time allows.](https://www.repostatus.org/badges/latest/inactive.svg)](https://www.repostatus.org/#inactive)
![](https://img.shields.io/badge/lifecycle-beta-509bf5.svg)
<img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/mkdocs-multirepo-plugin?style=plastic">

Build documentation in multiple repos into one site.

## Features

- **Distributed Documentation**: Keep docs close to the code but *findable* on one site.
- **Seperates Concerns**: Separate documentation from other files that go into building your mkdocs site (e.g., theme overrides).
- **Fast**: Documentation is imported asynchronously, using [asyncio](https://docs.python.org/3/library/asyncio.html).
- **Simple**: All configuration is done within the `plugins` or `nav` sections of your *mkdocs.yml* file.
- **Use in Production**: The plugin can be used in a CI/CD pipeline.

## OS Support

![Mac OS](https://img.shields.io/badge/mac%20os-000000?style=for-the-badge&logo=macos&logoColor=F0F0F0)
![Linux](https://img.shields.io/badge/Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black)
![Ubuntu](https://img.shields.io/badge/Ubuntu-E95420?style=for-the-badge&logo=ubuntu&logoColor=white)
![Windows](https://img.shields.io/badge/Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white)

## Dependencies

![Python](https://img.shields.io/badge/python-3670A0?style=for-the-badge&logo=python&logoColor=ffdd54)
![Git](https://img.shields.io/badge/git-%23F05033.svg?style=for-the-badge&logo=git&logoColor=white)

> Newer versions of Git preferred.

## Setup

Install plugin using pip:

```
pip install mkdocs-multirepo-plugin
```

Next, add the plugin to your `mkdocs.yml`

```yaml
plugins:
  - multirepo:
      # (optional) tells multirepo to cleanup the temporary directory after site is built.
      cleanup: true
      # if set the docs directory will not be removed when importing docs.
      # When using this with a nav section in an imported repo you must keep the
      # docs directory in the path (e.g., docs/path/to/file.md).
      keep_docs_dir: true
```

You'll now have 3 ways of importing docs:

- [plugins.multirepo.repos](#repos-config): Use this method if you don't have a `nav` section in the imported `mkdocs.yml` and want Mkdocs to generate navigation based on the directory structure. If there's a `nav` this configuration will be ignored since `nav` configuration takes precedence.
- [plugins.multirepo.nav_repos](#nav-repos-config): Use this if you have a `nav` section in your `mkdocs.yml` and want to refer to imported docs in the `nav` the same way as other docs in the repo. This can be used alongside `!import` statements.
- [!import](#import-statement): Used to specify docs to import to a section in the `nav`. The imported repo needs to have a `mkdocs.yml` file with a `nav` section as well.

## Import Statement

The plugin introduces the *!import* statement in your config's *nav* section. You can now use the import statement to add a documentation section, where the docs are pulled from the source repo.

<details><summary><b>!import Statement Sections</b></summary>

  - **{url}**: Only *required* part of *!import* statement (e.g., `https://github.com/{user}/{repo name}`).
  - **branch={branch}**: Tells *multirepo* what branch (or tag) to use. Defaults to *master* if not supplied. This is the same argument used in `git clone` (see [here](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---branchltnamegt)).
  - **docs_dir={path}**: The path to the *docs* directory for the section. Defaults to *docs/\** (a glob) if not supplied.
  - **multi_docs={True | False}**: If set to *True* all *docs* directories will be imported (more info [here](#α-multiple-docs-directories-in-imported-repo-alpha)).
  - **config={filename}.yml**: Tells *multirepo* the name of the config file, containing configuration for the plugin. The default value is also `mkdocs.yml`. This config file can live within the docs directory *or* in the parent directory.
  - **extra_imports=["{filename | path | glob}"]**: Use this if you want to import additional directories or files along with the docs.
  - **keep_docs_dir={True | False}**: If set the docs directory will not be removed when importing docs (i.e., `section/page.md` becomes `section/docs/page.md`)

</details>

```yaml
nav:
  - Home: 'index.md'
  - MicroService: '!import {url}?branch={branch}&docs_dir={path}&multi_docs={True | False}&config={filename}.yml&keep_docs_dir={True | False}'
```

*MicroService mkdocs.yml (located within the docs directory or the parent directory)*
```yaml
edit_uri: /blob/master/

nav:
  - Home: index.md
```

> Things to Note:
>
> - If using *!import* in the *nav*, the imported repo must have a *mkdocs.yml* (or another filename with a *?config={filename}.yml*) file with a *nav* section located in either the *docs* directory or the root directory.
> - *nav* takes precedence over *repos* (see below).
> - *{path}* can also be a [glob](https://en.wikipedia.org/wiki/Glob_(programming)) (e.g., `docs/*`).

## Repos Config

If you'd prefer *MkDocs* to build the site nav based on the directory structure, you can define your other repos within the *plugins* section.

```yaml
plugins:
  - search
  - multirepo:
      # (optional) tells multirepo to cleanup the temporary directory after site is built.
      cleanup: true
      # if set the docs directory will not be removed when importing docs. When using this with a nav section in an imported repo
      # you must keep the docs directory in the path (e.g., docs/path/to/file.md).
      keep_docs_dir: true
      repos:
          # There will be a navigation section with this section name
        - section: Backstage
          # you can define the edit uri path
          import_url: 'https://github.com/backstage/backstage?edit_uri=/blob/master/'
        - section: Monorepo
          import_url: 'https://github.com/backstage/mkdocs-monorepo-plugin?edit_uri=/blob/master/'
        - section: 'Techdocs-cli'
          # note that the branch is still specified in the url
          import_url: 'https://github.com/backstage/techdocs-cli?branch=main&edit_uri=/blob/main/'
        - section: FastAPI
          import_url: 'https://github.com/tiangolo/fastapi?docs_dir=docs/en/docs/*'
        - section: Monorepo Multi Docs
          import_url: https://github.com/backstage/mkdocs-monorepo-plugin?multi_docs=True&docs_dir=sample-docs/*
        - section: 'Django REST'
          section_path: python # Put this under the python menu entry
          import_url: 'https://github.com/encode/django-rest-framework'
        - section: 'Cookiecutter Pypackage'
          section_path: python # Put this under the python menu entry
          import_url: 'https://github.com/zillionare/cookiecutter-pypackage'
        - section: 'Pydantic'
          section_path: python # Put this under the python menu entry
          import_url: 'https://github.com/samuelcolvin/pydantic?branch=main'
```

## Nav Repos Config

```yaml
plugins:
  - search
  - multirepo:
      # (optional) tells multirepo to cleanup the temporary directory after site is built.
      cleanup: false
      nav_repos:
        - name: backstage
          import_url: https://github.com/backstage/backstage
          # forward slash is needed in '/README.md' so that only the README.md in the root
          # directory is imported and not all README.md files.
          imports: [
            docs/publishing.md, docs/integrations/index.md, /README.md,
            # asset files needed
            docs/assets/*
            ]
        - name: fast-api
          import_url: https://github.com/tiangolo/fastapi
          imports: [docs/en/docs/index.md]

nav:
  - Backstage:
      - Home: backstage/README.md
      - Integration: backstage/docs/integrations/index.md
      - Publishing: backstage/docs/publishing.md
  - FastAPI: fast-api/docs/en/docs/index.md
  # you can still use the !import statement
  - MkdocStrings: '!import https://github.com/mkdocstrings/mkdocstrings'
```

## Run

Once you're done configuring, run either `mkdocs serve` or `mkdocs build`. This will `import` the docs into a temporary directory and build the site.

![mkdocs-multirepo-plugin-demo](https://user-images.githubusercontent.com/57968347/183310333-07576062-d4e0-47d1-ac2c-9b682fea8b4e.gif)

## Additional Features

### α Multiple Docs Directories in Imported Repo (Alpha)

If an imported repo is a monorepo (i.e., has multiple *docs* directories), *multirepo* automatically includes them in the site when `multi_docs` is set to `True`.

Suppose *Microservice's* directory structure is this.

```
├───mkdocs.yml (required if nav section is defined)
├───README.md
├───project1
│   └───src
│   └───docs
│       └───assets
|         index.md
|         technical.md
├───project2
│   └───src
│   └───docs
│         index.md
```

By default, this directory turns into this.

```
├───mkdocs.yml (required if nav section is defined)
├───README.md
├───project1
│   └───assets
|     index.md
|     technical.md
├───project2
│     index.md
```

> Note:
> - If using the nav *!import* statement, make sure the nav paths reflect the new directory structure, which doesn't include *docs* directories.
> - *edit_urls* will still map to underlying markdown file based on the actual directory structure in the remote's repository.


### Use in CI/CD

If you want to use the plugin within Azure Pipelines or Github Actions, you'll need to define an access token.

#### Azure Pipelines

You'll need to define an `AccessToken` environment variable for the `mkdocs build` step. The access token should have access to `clone` all repos.

#### Github Actions

You'll need to define an `GithubAccessToken` environment variable for the `mkdocs build` step. The access token should have access to `clone` all repos. This can be a personal access token or one from a GitHub App.

#### Azure Pipeline Step Example

```yaml
- script: |
    source ./env/bin/activate
    mkdocs build
  env:
    AccessToken: $(System.AccessToken)
  displayName: 'Build MkDocs Site'
```

### β Development in Imported Repos (Beta)

For `mkdocs serve` to work properly in an imported repo (a repo that is imported in the parent site), *you will need to add the multirepo plugin within the imported repo as well as the parent repo*, including the following configuration.

> Notes:
> - You will also need to have `plugins` and `packages` the parent repo uses installed within your local `venv`.
> - See documentation on the [set](https://git-scm.com/docs/git-sparse-checkout#Documentation/git-sparse-checkout.txt-emsetem) git command for `sparse-checkout` if you are confused with what `paths` can contain.

```yml
plugins:
  multirepo:
    imported_repo: true
    url: https://github.com/squidfunk/mkdocs-material
    section_name: Backstage
    # dirs/files needed for building the site
    # any path in docs will be included. For example, index.md is the
    # homepage of the parent site
    paths: ["material/*", "mkdocs.yml", "docs/index.md"]
    custom_dir: material
    yml_file: mkdocs.yml # this can also be a relative path
    branch: master
```

Writers can now run `mkdocs serve` within their local repo, using the main site's configuration, custom theming and features. This means all development is distributed, without technical writers having to switch repos.

> Backstage with Material theme

![site image](assets/backstage-material-theme.png)

## Contributing

You'll need to install [Poetry](https://python-poetry.org) and Git to contribute and run tests locally.

### Setup

> Assumes you have `poetry` installed and in your path

```~ poetry install & poetry shell```

### Running Tests

Tests were modeled off of [mkdocs-monorepo-plugin](https://github.com/backstage/mkdocs-monorepo-plugin/blob/master/docs/CONTRIBUTING.md). To run the test suite you'll need:

- Python
- Git
- Docker
- MkDocs

### Integration Testing

The command below will use Docker to run our test suites in numerous Python versions. It may take some time on first run, but should be very fast afterwards. When you're done, feel free to run `docker prune` to clear them from your local cache. We use the `slim` versions of the public `python` images from [Docker Hub](https://hub.docker.com).
```
$ ./__tests__/test.sh
```
For faster tests, you can opt to run in Python 3.7 rather than all supported Python versions:
```
$ PYTHON_37_ONLY=1 ./__tests__/test.sh
```

### Unit Testing

```
$ python[3] -m unittest tests.unittests
```


            

Raw data

            {
    "_id": null,
    "home_page": "https://pypi.org/project/mkdocs-multirepo-plugin/",
    "name": "mkdocs-multirepo-plugin",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "mkdocs,docs,documentation",
    "author": "jdoiro3",
    "author_email": "josephdoiron1234@yahoo.com",
    "download_url": "https://files.pythonhosted.org/packages/dd/a8/057c6add6606f0f055749b1020f526ead46016793c5bed5abfa1e6422d5e/mkdocs_multirepo_plugin-0.7.0.tar.gz",
    "platform": null,
    "description": "If you like this plugin and want me to continue maintaining it in my free time, please buy me a [beer \ud83c\udf7a](https://www.buymeacoffee.com/jdoiro) or sponser this plugin!\n\n# mkdocs-multirepo-plugin\n\n[![](https://github.com/jdoiro3/mkdocs-multirepo-plugin/workflows/Tests/badge.svg)](https://github.com/jdoiro3/mkdocs-multirepo-plugin/actions)\n[![](https://github.com/jdoiro3/mkdocs-multirepo-plugin/workflows/Build%2C%20Test%20%26%20Deploy/badge.svg)](https://github.com/jdoiro3/mkdocs-multirepo-plugin/actions)\n[![PyPI](https://img.shields.io/pypi/v/mkdocs-multirepo-plugin)](https://pypi.org/project/mkdocs-multirepo-plugin/)\n[![Project Status: Inactive \u2013 The project has reached a stable, usable state but is no longer being actively developed; support/maintenance will be provided as time allows.](https://www.repostatus.org/badges/latest/inactive.svg)](https://www.repostatus.org/#inactive)\n![](https://img.shields.io/badge/lifecycle-beta-509bf5.svg)\n<img alt=\"PyPI - Downloads\" src=\"https://img.shields.io/pypi/dm/mkdocs-multirepo-plugin?style=plastic\">\n\nBuild documentation in multiple repos into one site.\n\n## Features\n\n- **Distributed Documentation**: Keep docs close to the code but *findable* on one site.\n- **Seperates Concerns**: Separate documentation from other files that go into building your mkdocs site (e.g., theme overrides).\n- **Fast**: Documentation is imported asynchronously, using [asyncio](https://docs.python.org/3/library/asyncio.html).\n- **Simple**: All configuration is done within the `plugins` or `nav` sections of your *mkdocs.yml* file.\n- **Use in Production**: The plugin can be used in a CI/CD pipeline.\n\n## OS Support\n\n![Mac OS](https://img.shields.io/badge/mac%20os-000000?style=for-the-badge&logo=macos&logoColor=F0F0F0)\n![Linux](https://img.shields.io/badge/Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black)\n![Ubuntu](https://img.shields.io/badge/Ubuntu-E95420?style=for-the-badge&logo=ubuntu&logoColor=white)\n![Windows](https://img.shields.io/badge/Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white)\n\n## Dependencies\n\n![Python](https://img.shields.io/badge/python-3670A0?style=for-the-badge&logo=python&logoColor=ffdd54)\n![Git](https://img.shields.io/badge/git-%23F05033.svg?style=for-the-badge&logo=git&logoColor=white)\n\n> Newer versions of Git preferred.\n\n## Setup\n\nInstall plugin using pip:\n\n```\npip install mkdocs-multirepo-plugin\n```\n\nNext, add the plugin to your `mkdocs.yml`\n\n```yaml\nplugins:\n  - multirepo:\n      # (optional) tells multirepo to cleanup the temporary directory after site is built.\n      cleanup: true\n      # if set the docs directory will not be removed when importing docs.\n      # When using this with a nav section in an imported repo you must keep the\n      # docs directory in the path (e.g., docs/path/to/file.md).\n      keep_docs_dir: true\n```\n\nYou'll now have 3 ways of importing docs:\n\n- [plugins.multirepo.repos](#repos-config): Use this method if you don't have a `nav` section in the imported `mkdocs.yml` and want Mkdocs to generate navigation based on the directory structure. If there's a `nav` this configuration will be ignored since `nav` configuration takes precedence.\n- [plugins.multirepo.nav_repos](#nav-repos-config): Use this if you have a `nav` section in your `mkdocs.yml` and want to refer to imported docs in the `nav` the same way as other docs in the repo. This can be used alongside `!import` statements.\n- [!import](#import-statement): Used to specify docs to import to a section in the `nav`. The imported repo needs to have a `mkdocs.yml` file with a `nav` section as well.\n\n## Import Statement\n\nThe plugin introduces the *!import* statement in your config's *nav* section. You can now use the import statement to add a documentation section, where the docs are pulled from the source repo.\n\n<details><summary><b>!import Statement Sections</b></summary>\n\n  - **{url}**: Only *required* part of *!import* statement (e.g., `https://github.com/{user}/{repo name}`).\n  - **branch={branch}**: Tells *multirepo* what branch (or tag) to use. Defaults to *master* if not supplied. This is the same argument used in `git clone` (see [here](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---branchltnamegt)).\n  - **docs_dir={path}**: The path to the *docs* directory for the section. Defaults to *docs/\\** (a glob) if not supplied.\n  - **multi_docs={True | False}**: If set to *True* all *docs* directories will be imported (more info [here](#\u03b1-multiple-docs-directories-in-imported-repo-alpha)).\n  - **config={filename}.yml**: Tells *multirepo* the name of the config file, containing configuration for the plugin. The default value is also `mkdocs.yml`. This config file can live within the docs directory *or* in the parent directory.\n  - **extra_imports=[\"{filename | path | glob}\"]**: Use this if you want to import additional directories or files along with the docs.\n  - **keep_docs_dir={True | False}**: If set the docs directory will not be removed when importing docs (i.e., `section/page.md` becomes `section/docs/page.md`)\n\n</details>\n\n```yaml\nnav:\n  - Home: 'index.md'\n  - MicroService: '!import {url}?branch={branch}&docs_dir={path}&multi_docs={True | False}&config={filename}.yml&keep_docs_dir={True | False}'\n```\n\n*MicroService mkdocs.yml (located within the docs directory or the parent directory)*\n```yaml\nedit_uri: /blob/master/\n\nnav:\n  - Home: index.md\n```\n\n> Things to Note:\n>\n> - If using *!import* in the *nav*, the imported repo must have a *mkdocs.yml* (or another filename with a *?config={filename}.yml*) file with a *nav* section located in either the *docs* directory or the root directory.\n> - *nav* takes precedence over *repos* (see below).\n> - *{path}* can also be a [glob](https://en.wikipedia.org/wiki/Glob_(programming)) (e.g., `docs/*`).\n\n## Repos Config\n\nIf you'd prefer *MkDocs* to build the site nav based on the directory structure, you can define your other repos within the *plugins* section.\n\n```yaml\nplugins:\n  - search\n  - multirepo:\n      # (optional) tells multirepo to cleanup the temporary directory after site is built.\n      cleanup: true\n      # if set the docs directory will not be removed when importing docs. When using this with a nav section in an imported repo\n      # you must keep the docs directory in the path (e.g., docs/path/to/file.md).\n      keep_docs_dir: true\n      repos:\n          # There will be a navigation section with this section name\n        - section: Backstage\n          # you can define the edit uri path\n          import_url: 'https://github.com/backstage/backstage?edit_uri=/blob/master/'\n        - section: Monorepo\n          import_url: 'https://github.com/backstage/mkdocs-monorepo-plugin?edit_uri=/blob/master/'\n        - section: 'Techdocs-cli'\n          # note that the branch is still specified in the url\n          import_url: 'https://github.com/backstage/techdocs-cli?branch=main&edit_uri=/blob/main/'\n        - section: FastAPI\n          import_url: 'https://github.com/tiangolo/fastapi?docs_dir=docs/en/docs/*'\n        - section: Monorepo Multi Docs\n          import_url: https://github.com/backstage/mkdocs-monorepo-plugin?multi_docs=True&docs_dir=sample-docs/*\n        - section: 'Django REST'\n          section_path: python # Put this under the python menu entry\n          import_url: 'https://github.com/encode/django-rest-framework'\n        - section: 'Cookiecutter Pypackage'\n          section_path: python # Put this under the python menu entry\n          import_url: 'https://github.com/zillionare/cookiecutter-pypackage'\n        - section: 'Pydantic'\n          section_path: python # Put this under the python menu entry\n          import_url: 'https://github.com/samuelcolvin/pydantic?branch=main'\n```\n\n## Nav Repos Config\n\n```yaml\nplugins:\n  - search\n  - multirepo:\n      # (optional) tells multirepo to cleanup the temporary directory after site is built.\n      cleanup: false\n      nav_repos:\n        - name: backstage\n          import_url: https://github.com/backstage/backstage\n          # forward slash is needed in '/README.md' so that only the README.md in the root\n          # directory is imported and not all README.md files.\n          imports: [\n            docs/publishing.md, docs/integrations/index.md, /README.md,\n            # asset files needed\n            docs/assets/*\n            ]\n        - name: fast-api\n          import_url: https://github.com/tiangolo/fastapi\n          imports: [docs/en/docs/index.md]\n\nnav:\n  - Backstage:\n      - Home: backstage/README.md\n      - Integration: backstage/docs/integrations/index.md\n      - Publishing: backstage/docs/publishing.md\n  - FastAPI: fast-api/docs/en/docs/index.md\n  # you can still use the !import statement\n  - MkdocStrings: '!import https://github.com/mkdocstrings/mkdocstrings'\n```\n\n## Run\n\nOnce you're done configuring, run either `mkdocs serve` or `mkdocs build`. This will `import` the docs into a temporary directory and build the site.\n\n![mkdocs-multirepo-plugin-demo](https://user-images.githubusercontent.com/57968347/183310333-07576062-d4e0-47d1-ac2c-9b682fea8b4e.gif)\n\n## Additional Features\n\n### \u03b1 Multiple Docs Directories in Imported Repo (Alpha)\n\nIf an imported repo is a monorepo (i.e., has multiple *docs* directories), *multirepo* automatically includes them in the site when `multi_docs` is set to `True`.\n\nSuppose *Microservice's* directory structure is this.\n\n```\n\u251c\u2500\u2500\u2500mkdocs.yml (required if nav section is defined)\n\u251c\u2500\u2500\u2500README.md\n\u251c\u2500\u2500\u2500project1\n\u2502   \u2514\u2500\u2500\u2500src\n\u2502   \u2514\u2500\u2500\u2500docs\n\u2502       \u2514\u2500\u2500\u2500assets\n|         index.md\n|         technical.md\n\u251c\u2500\u2500\u2500project2\n\u2502   \u2514\u2500\u2500\u2500src\n\u2502   \u2514\u2500\u2500\u2500docs\n\u2502         index.md\n```\n\nBy default, this directory turns into this.\n\n```\n\u251c\u2500\u2500\u2500mkdocs.yml (required if nav section is defined)\n\u251c\u2500\u2500\u2500README.md\n\u251c\u2500\u2500\u2500project1\n\u2502   \u2514\u2500\u2500\u2500assets\n|     index.md\n|     technical.md\n\u251c\u2500\u2500\u2500project2\n\u2502     index.md\n```\n\n> Note:\n> - If using the nav *!import* statement, make sure the nav paths reflect the new directory structure, which doesn't include *docs* directories.\n> - *edit_urls* will still map to underlying markdown file based on the actual directory structure in the remote's repository.\n\n\n### Use in CI/CD\n\nIf you want to use the plugin within Azure Pipelines or Github Actions, you'll need to define an access token.\n\n#### Azure Pipelines\n\nYou'll need to define an `AccessToken` environment variable for the `mkdocs build` step. The access token should have access to `clone` all repos.\n\n#### Github Actions\n\nYou'll need to define an `GithubAccessToken` environment variable for the `mkdocs build` step. The access token should have access to `clone` all repos. This can be a personal access token or one from a GitHub App.\n\n#### Azure Pipeline Step Example\n\n```yaml\n- script: |\n    source ./env/bin/activate\n    mkdocs build\n  env:\n    AccessToken: $(System.AccessToken)\n  displayName: 'Build MkDocs Site'\n```\n\n### \u03b2 Development in Imported Repos (Beta)\n\nFor `mkdocs serve` to work properly in an imported repo (a repo that is imported in the parent site), *you will need to add the multirepo plugin within the imported repo as well as the parent repo*, including the following configuration.\n\n> Notes:\n> - You will also need to have `plugins` and `packages` the parent repo uses installed within your local `venv`.\n> - See documentation on the [set](https://git-scm.com/docs/git-sparse-checkout#Documentation/git-sparse-checkout.txt-emsetem) git command for `sparse-checkout` if you are confused with what `paths` can contain.\n\n```yml\nplugins:\n  multirepo:\n    imported_repo: true\n    url: https://github.com/squidfunk/mkdocs-material\n    section_name: Backstage\n    # dirs/files needed for building the site\n    # any path in docs will be included. For example, index.md is the\n    # homepage of the parent site\n    paths: [\"material/*\", \"mkdocs.yml\", \"docs/index.md\"]\n    custom_dir: material\n    yml_file: mkdocs.yml # this can also be a relative path\n    branch: master\n```\n\nWriters can now run `mkdocs serve` within their local repo, using the main site's configuration, custom theming and features. This means all development is distributed, without technical writers having to switch repos.\n\n> Backstage with Material theme\n\n![site image](assets/backstage-material-theme.png)\n\n## Contributing\n\nYou'll need to install [Poetry](https://python-poetry.org) and Git to contribute and run tests locally.\n\n### Setup\n\n> Assumes you have `poetry` installed and in your path\n\n```~ poetry install & poetry shell```\n\n### Running Tests\n\nTests were modeled off of [mkdocs-monorepo-plugin](https://github.com/backstage/mkdocs-monorepo-plugin/blob/master/docs/CONTRIBUTING.md). To run the test suite you'll need:\n\n- Python\n- Git\n- Docker\n- MkDocs\n\n### Integration Testing\n\nThe command below will use Docker to run our test suites in numerous Python versions. It may take some time on first run, but should be very fast afterwards. When you're done, feel free to run `docker prune` to clear them from your local cache. We use the `slim` versions of the public `python` images from [Docker Hub](https://hub.docker.com).\n```\n$ ./__tests__/test.sh\n```\nFor faster tests, you can opt to run in Python 3.7 rather than all supported Python versions:\n```\n$ PYTHON_37_ONLY=1 ./__tests__/test.sh\n```\n\n### Unit Testing\n\n```\n$ python[3] -m unittest tests.unittests\n```\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Build documentation in multiple repos into one site.",
    "version": "0.7.0",
    "project_urls": {
        "Homepage": "https://pypi.org/project/mkdocs-multirepo-plugin/",
        "Repository": "https://github.com/jdoiro3/mkdocs-multirepo-plugin"
    },
    "split_keywords": [
        "mkdocs",
        "docs",
        "documentation"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "322b0a1dbc0bc8e996c980bf0e92d6e3f8b36bf5bfb1eb78d0a0ff96a8a17315",
                "md5": "2ff8bb049233a8f9359ccae0318f1dfc",
                "sha256": "1034fc2aadafedb9d789eb2fb9181b5121c297f7e123beebd51c19e1e6ee94e5"
            },
            "downloads": -1,
            "filename": "mkdocs_multirepo_plugin-0.7.0-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "2ff8bb049233a8f9359ccae0318f1dfc",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": null,
            "size": 20844,
            "upload_time": "2024-01-19T13:45:48",
            "upload_time_iso_8601": "2024-01-19T13:45:48.881780Z",
            "url": "https://files.pythonhosted.org/packages/32/2b/0a1dbc0bc8e996c980bf0e92d6e3f8b36bf5bfb1eb78d0a0ff96a8a17315/mkdocs_multirepo_plugin-0.7.0-py2.py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "dda8057c6add6606f0f055749b1020f526ead46016793c5bed5abfa1e6422d5e",
                "md5": "6a608291bb491546350dbdbb8f6c5ca2",
                "sha256": "efd70eb4ef4fdffab5e3af1d5d4da31d0463cbdbe5ea539cea31fbaa153c6fef"
            },
            "downloads": -1,
            "filename": "mkdocs_multirepo_plugin-0.7.0.tar.gz",
            "has_sig": false,
            "md5_digest": "6a608291bb491546350dbdbb8f6c5ca2",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 20817,
            "upload_time": "2024-01-19T13:45:50",
            "upload_time_iso_8601": "2024-01-19T13:45:50.939065Z",
            "url": "https://files.pythonhosted.org/packages/dd/a8/057c6add6606f0f055749b1020f526ead46016793c5bed5abfa1e6422d5e/mkdocs_multirepo_plugin-0.7.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-01-19 13:45:50",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "jdoiro3",
    "github_project": "mkdocs-multirepo-plugin",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "mkdocs-multirepo-plugin"
}
        
Elapsed time: 0.17784s