# Qtpass Docs

> Documentation guide for QtPass - README, FAQ, localization

- Skill: `ijhack/qtpass-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ijhack/qtpass-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ijhack/qtpass-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: GPL-3.0-or-later
- Author: ijhack (https://skillmd.com/u/ijhack)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ijhack/qtpass-docs

---


# Project Documentation

## QtPass Documentation Files

| File               | Purpose                                     |
| ------------------ | ------------------------------------------- |
| README.md          | Main documentation, installation, usage     |
| FAQ.md             | Frequently asked questions, troubleshooting |
| CHANGELOG.md       | Release history, changes                    |
| CONTRIBUTING.md    | Developer contribution guidelines           |
| CODE_OF_CONDUCT.md | Community code of conduct                   |
| Doxyfile           | API documentation configuration             |
| Windows.md         | Windows-specific installation and build     |

## README.md Sections

- Badges (build, license, version)
- Description
- Features
- Installation (Linux, macOS, Windows)
- Usage / Getting Started
- Configuration
- Acknowledgments

## FAQ.md Sections

- Installation issues
- Configuration issues
- GPG/Key issues
- Git integration
- Platform-specific (macOS, Windows, Linux)

### FAQ Template

```markdown
## Question Title

**Problem:** Description of the issue

**Solution:** Step-by-step solution

**Related:** Links to relevant issues
```

## Localization

See [qtpass-localization](../qtpass-localization/SKILL.md) skill for comprehensive guide.

## Docs Build

### API Documentation

```bash
# Generate API docs
doxygen Doxyfile
# Or use project-specific docs command

# View
open docs/index.html
```

## Linting

**THIS IS THE PATTERN - always run before pushing:**

```bash
# Check formatting (this is the pattern)
npx prettier --check "**/*.md"

# Format all markdown files
npx prettier --write "**/*.md"

# Format specific file
npx prettier --write README.md
```

### Markdown (prettier)

```bash
npx prettier --write <markdown-file>
npx prettier --write "**/*/SKILL.md"
```

### YAML (prettier)

```bash
npx prettier --write <yaml-file>
npx prettier --write .github/workflows/*.yml
```

## Updating Documentation

### Adding New FAQ Entry

1. Edit `FAQ.md`
2. Use the FAQ template section above
3. Run prettier: `npx prettier --write FAQ.md`
4. Test the changes render correctly

### Updating Version in readme

When releasing a new version, update download links:

```bash
# Find version strings in README
grep -n "1\.5\|download" README.md
```

Update:

- Download links for each platform
- Badge version numbers
- Any version-specific instructions

### Building API Docs

```bash
# Generate with doxygen
doxygen Doxyfile

# Output goes to docs/
ls docs/index.html
```

CI pins **Doxygen 1.17.0** and treats warnings as errors; a local Doxygen of a
different version may report differently. The `docs.yml` install step fetches
the pinned binary from the GitHub release mirror first, then doxygen.nl, with
retries (doxygen.nl outages previously caused spurious `docs` failures).

## Common Pitfalls

### Forgetting to Run Prettier

Always format Markdown with prettier before committing:

```bash
# Wrong - may fail CI
git commit -m "Update FAQ"

# Correct
npx prettier --write FAQ.md
git commit -m "Update FAQ"
```

### Broken Links

When adding links to issues or PRs:

```bash
# Use full GitHub URLs (they redirect correctly)
[Issue #123](https://github.com/IJHack/QtPass/issues/123)

# Not relative paths
[Issue #123](issues/123)  # Broken
```

### Outdated Platform Instructions

QtPass changes frequently. When updating installation instructions:

- Verify the commands still work
- Check for new dependencies
- Update screenshots if UI changed

### CHANGELOG Format

Keep CHANGELOG entries consistent:

```markdown
## [1.5.1] - 2026-03-30

### Fixed

- Issue #123: Description of fix

### Added

- New feature description
```

### Doxygen Comments in Code

When adding new public APIs, every public symbol in a header needs a Doxygen doc block:

```cpp
/**
 * @brief Brief description.
 * @param param1 Description of first parameter.
 * @return Description of return value.
 */
```

The CI enforces **zero Doxygen warnings** via `docs.yml`. `WARN_AS_ERROR = FAIL_ON_WARNINGS` in `Doxyfile` causes the step to fail on any undocumented public symbol.

#### Enforced Doxyfile settings

| Setting            | Value              | Purpose                                           |
| ------------------ | ------------------ | ------------------------------------------------- |
| `FILE_PATTERNS`    | `*.cpp *.h *.md`   | Includes cpp, header, and Markdown files          |
| `EXTRACT_ALL`      | `NO`               | Required for `WARN_NO_PARAMDOC` to work           |
| `WARN_NO_PARAMDOC` | `YES`              | Requires `@param`/`@return` on all public symbols |
| `WARN_AS_ERROR`    | `FAIL_ON_WARNINGS` | Fails CI on any warning                           |

#### Run locally before pushing

```bash
doxygen Doxyfile
# Any output = warning = CI will fail
```

#### Common doc mistakes that cause warnings

- Unnamed parameters in header declarations — name every parameter
- Orphaned `/** */` blocks not immediately above their declaration
- Missing `@return` on non-void functions (required with `WARN_NO_PARAMDOC = YES`)
- Signals with unnamed parameters (Qt signals need docs too)
- `@unknowncommand` typos in doc blocks