https://github.com/dielduarte/janusdoc
https://github.com/dielduarte/janusdoc
Last synced: 21 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/dielduarte/janusdoc
- Owner: dielduarte
- License: other
- Created: 2025-12-14T21:41:25.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2025-12-29T02:47:52.000Z (about 2 months ago)
- Last Synced: 2025-12-31T20:23:24.420Z (about 1 month ago)
- Language: TypeScript
- Size: 538 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Janusdoc
Installation •
Quick Start •
Commands •
CI/CD •
Evaluation Suite
AI-powered documentation update suggester for pull requests. JanusDoc analyzes code changes in your PRs and automatically suggests documentation updates based on your project's existing docs and style guide.
## Installation
```bash
npm install -g janusdoc
```
Or use with npx:
```bash
npx janusdoc [command]
```
## Quick Start
1. Initialize JanusDoc in your project:
```bash
janusdoc init
```
2. Analyze a pull request:
```bash
janusdoc run --pr 123 --repo owner/repo
```
## Commands
### `janusdoc init`
Initialize JanusDoc in your current project. This command will:
- Detect or create your documentation directory
- Generate a `.janusdoc.json` configuration file
- Scan your existing documentation
- Generate an AI-powered style guide based on your docs
- Generate a documentation map describing each file's purpose and relationships
- Create embeddings for semantic search
**Options:**
- `-d, --docs-path ` - Path to documentation directory (default: auto-detected or "docs")
**Example:**
```bash
janusdoc init
janusdoc init --docs-path documentation
```
**Environment Variables:**
- `OPENAI_API_KEY` - Required for AI-powered features (style guide generation and semantic search)
### `janusdoc run`
Analyze a pull request and suggest documentation updates. Posts a comment on the PR with suggestions if documentation updates are needed.
**Required Options:**
- `-p, --pr ` - Pull request number
- `-r, --repo ` - Repository in owner/repo format
**Optional:**
- `-t, --token ` - GitHub token (defaults to `GITHUB_TOKEN` environment variable)
**Example:**
```bash
# Using GITHUB_TOKEN from environment
janusdoc run --pr 42 --repo myorg/myproject
# Providing token explicitly
janusdoc run --pr 42 --repo myorg/myproject --token ghp_xxxxx
```
**Environment Variables:**
- `GITHUB_TOKEN` - GitHub personal access token with repo access
- `OPENAI_API_KEY` - Required for AI-powered analysis
## Configuration
After running `janusdoc init`, a `.janusdoc.json` file is created:
```json
{
"docsPath": "docs"
}
```
### Configuration Options
| Option | Type | Default | Description |
| ------------------ | ------ | -------- | ----------------------------------------------------------------- |
| `docsPath` | string | `"docs"` | Path to your documentation directory |
| `search.topN` | number | `15` | Maximum number of relevant docs to consider during analysis |
| `search.threshold` | number | `0.15` | Minimum similarity score (0-1) for docs to be considered relevant |
**Example with all options:**
```json
{
"docsPath": "documentation",
"search": {
"topN": 5,
"threshold": 0.5
}
}
```
> **Tip:** Lower the `threshold` if JanusDoc is missing relevant docs. Raise it if you're getting too many false positives.
### Generated Files
JanusDoc also creates a `.janusdoc/` directory containing:
- `auto_styleguide.md` - Auto-generated documentation style guide (can be customized)
- `doc_map.md` - Documentation map describing each file's purpose, when to update it, and related files
- `embeddings.json` - Vector embeddings for semantic search
## How It Works
1. **Initialization**: JanusDoc scans your documentation and generates:
- A style guide based on your existing docs
- A documentation map describing each file's purpose and relationships
- Vector embeddings for semantic search
2. **PR Analysis**: When analyzing a PR, JanusDoc:
- Fetches the code changes from GitHub
- Summarizes the changes using AI (including documentation impact)
- Uses semantic search to find relevant documentation
- Uses the documentation map to understand file relationships
- Analyzes whether documentation updates are needed
- Posts suggestions as a PR comment
## CI/CD Integration
Add JanusDoc to your GitHub Actions workflow:
```yaml
name: Documentation Check
on: [pull_request]
jobs:
docs-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: "20"
- name: Run JanusDoc
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: |
npx janusdoc run --pr ${{ github.event.pull_request.number }} --repo ${{ github.repository }}
```
## Requirements
- Node.js 18 or higher
- GitHub personal access token with `repo` scope
- OpenAI API key for AI-powered features
## License
https://osaasy.dev/