How to Set Up a Continuous Documentation with DeepDocs

DeepDocs helps you automate documentation updates by continuously monitoring your codebase and updating high-level docs like READMEs, SDK guides, API refs and tutorials.

This guide walks you through setting up a continuous documentation using DeepDocs. It will cover cases when your code and docs live in the same repository (monorepo) or they live in separate repositories.

---

✅ Prerequisites

• Install the DeepDocs App on:
• Your Github repository containing your source code and docs (monorepo)

• And optionally, your external docs repository (if separate)

• Decide which branch you want DeepDocs to monitor (e.g. feature/preview or main branch).

---

1️⃣ Monorepo Setup: Code and Docs in the Same Repo

In a monorepo setup, both source code and documentation live in the same repo. DeepDocs will monitor for code changes in the specific branch on every commit, and update the doc files if they get outdated.

Place a deepdocs.yml file at the root of your repo, in the branch where you're working on e.g. main or a feature branch. Then make your first commit to trigger documentation scans.

Example:

target:
  - url: "docs/"
  - url: "examples/"

include:  []

reinit: "a-random-string"

• target.url: A Relative path to a docs files or folder, or a GitHub URL if pointing to an external repo.

• include: A list of specific source code files or folders to monitor e.g. "src". If left empty, DeepDocs will monitor the entire repo for code changes

• reinit: A random string used to reinitialize doc scans.

---

2️⃣ Separate Repo Setup: Code and Docs in Different Repos

In this setup, your code and docs live in separate GitHub repositories. DeepDocs must be installed on both repositories.

However, the deepdocs.yml config should be added only to the code repository, and should speficiy the target url of the docs file or folder.

Example:

target:
  - url: "https://github.com/my-org/docs-repo/tree/main/guides/"

include:  []

reinit: "a-random-string"

ℹ️ target.url: Must be a GitHub URL pointing to the file or folder on the docs repository.

---

🧩 What happens next

• On the first commit of deepdocs.yml, DeepDocs gets initialized and runs a deep scan of your current branch
• You get a report on which docs are outdated and why (as commit comment and email notification)

• Then it updates those docs in a separate branch named deepdocs-update-<branch>-<commit_sha>. Here, <branch> is your current branch name and <commit_sha> is the commit of deepdocs.yml

  • If the target is in the same repository, the branch is created out of your current branch.
  • If the target is in an external repository, the branch is created from the external repo’s branch (e.g., main).

• You can review and merge the changes like any regular PR.

• Every subsequent commit triggers a documentation scan just like the steps above

A report on documentation scan by DeepDocs

---

📝 Tips

• Use feature branches (like feature/preview) for staging doc changes alongside pre-release code.
• Use include to specify only the code files or folders that should trigger doc updates (e.g., exclude legacy modules, example scripts etc.)
• Reinitialize DeepDocs by updating the reinit value in the config when the source code changes significantly between two commits,

---

🧪 Example Scenarios

Monorepo setup

target:
  - url:  "docs/"
  - url:  "examples/"

include:
  -  "src"
  -  "requirements.txt"

reinit: "Xhxp8Z1z"

External repo setup

target:
  - url: "https://github.com/my-org/docs-repo/tree/main/guides/"

include:
  -  "src"
  -  "requirements.tx"

reinit: "Xhxp8Z1z"

---