From de840124a3dc943012351f5ac5a2e510f10b1a20 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 11 Mar 2026 14:04:34 +0000 Subject: [PATCH 1/5] Initial plan From bafe61af28d983e7f8fd25c31cb86e2cae0a5225 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 11 Mar 2026 14:11:20 +0000 Subject: [PATCH 2/5] docs: add mkdocs and read the docs setup Co-authored-by: mbe24 <7420624+mbe24@users.noreply.github.com> --- .github/workflows/ci.yml | 11 +++++++++++ .readthedocs.yml | 19 +++++++++++++++++++ README.md | 16 ++++++++++++++++ docs/configuration.md | 17 +++++++++++++++++ docs/getting-started.md | 21 +++++++++++++++++++++ docs/index.md | 8 ++++++++ docs/internal/README.md | 5 +++++ docs/requirements.txt | 1 + mkdocs.yml | 18 ++++++++++++++++++ 9 files changed, 116 insertions(+) create mode 100644 .readthedocs.yml create mode 100644 docs/configuration.md create mode 100644 docs/getting-started.md create mode 100644 docs/index.md create mode 100644 docs/internal/README.md create mode 100644 docs/requirements.txt create mode 100644 mkdocs.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3224b10..95c0494 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -40,6 +40,17 @@ jobs: - name: Unit tests run: cargo test --features telemetry-otel + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: "3.12" + + - name: Install docs dependencies + run: pip install -r docs/requirements.txt + + - name: Docs build (strict) + run: mkdocs build --strict + - name: Integration tests if: env.GITHUB_TOKEN != '' env: diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..b17fce9 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,19 @@ +version: 2 + +build: + os: ubuntu-24.04 + tools: + python: "3.12" + +mkdocs: + configuration: mkdocs.yml + +python: + install: + - requirements: docs/requirements.txt + +versions: + only: + - main + - stable + - /^v\d+\.\d+\.\d+$/ diff --git a/README.md b/README.md index d424da3..f6af3e3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # 99problems [![CI](https://github.com/mbe24/99problems/actions/workflows/ci.yml/badge.svg)](https://github.com/mbe24/99problems/actions/workflows/ci.yml) +[![Docs](https://readthedocs.org/projects/99problems/badge/?version=latest)](https://99problems.readthedocs.io/en/latest/) [![npm](https://img.shields.io/npm/v/@mbe24/99problems?color=7C3AED&label=npm)](https://www.npmjs.com/package/@mbe24/99problems) [![crates.io](https://img.shields.io/crates/v/problems99?color=7C3AED&label=crates.io)](https://crates.io/crates/problems99) ![platforms](https://img.shields.io/badge/platforms-win%20%7C%20linux%20%7C%20macos-7C3AED) @@ -16,6 +17,10 @@ Software tasks often depend on decisions made in earlier issues and pull request This is useful for Agentic Engineering workflows and for humans doing direct investigation in terminals or scripts. +## Documentation + +Public docs are hosted on Read the Docs: [99problems.readthedocs.io](https://99problems.readthedocs.io/). + ## Installation ```bash @@ -207,6 +212,17 @@ If 99problems saves you time, you can support ongoing maintenance via [GitHub Sp See [CONTRIBUTING.md](CONTRIBUTING.md). +## Documentation Authoring + +- Public docs source lives under [`docs/`](docs/). +- Internal-only docs should live under [`docs/internal/`](docs/internal/) and are excluded from the published site. +- Validate docs locally with: + +```bash +pip install -r docs/requirements.txt +mkdocs build --strict +``` + ## License See [LICENSE](LICENSE). diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..6c4689f --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,17 @@ +# Configuration + +`99problems` reads instance-based TOML configuration from: + +- `~/.99problems` +- `./.99problems` + +Minimal example: + +```toml +[instances.github] +platform = "github" +repo = "owner/repo" +token = "ghp_your_token" +``` + +See the [README configuration section](https://github.com/mbe24/99problems/blob/main/README.md#configuration) for the complete configuration reference. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..8623864 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,21 @@ +# Getting Started + +Install `99problems`: + +```bash +npm install -g @mbe24/99problems +# or +cargo install problems99 +``` + +Fetch a GitHub issue: + +```bash +99problems get --repo schemaorg/schemaorg --id 1842 +``` + +Search GitLab issues: + +```bash +99problems get --platform gitlab -q "repo:veloren/veloren is:issue state:closed terrain" +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..6ccd247 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,8 @@ +# 99problems Documentation + +`99problems` is an AI-native CLI for retrieving issue and pull request context across GitHub, GitLab, Jira, and Bitbucket. + +Use this site for task-focused docs, and the repository README for the full project overview: + +- [Project README](https://github.com/mbe24/99problems/blob/main/README.md) +- [Contributing Guide](https://github.com/mbe24/99problems/blob/main/CONTRIBUTING.md) diff --git a/docs/internal/README.md b/docs/internal/README.md new file mode 100644 index 0000000..b810477 --- /dev/null +++ b/docs/internal/README.md @@ -0,0 +1,5 @@ +# Internal Documentation + +This directory is for non-public documentation. + +Content under `docs/internal/` is intentionally excluded from the published MkDocs navigation and output. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..f2caded --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +mkdocs==1.6.1 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..0bb74dd --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,18 @@ +site_name: 99problems +site_description: Documentation for the 99problems CLI +site_url: https://99problems.readthedocs.io/ +repo_url: https://github.com/mbe24/99problems +repo_name: mbe24/99problems +edit_uri: edit/main/docs/ +docs_dir: docs +strict: true + +exclude_docs: internal/** + +theme: + name: readthedocs + +nav: + - Home: index.md + - Getting Started: getting-started.md + - Configuration: configuration.md From 6ac308ed0cbc8aec59a01ae04c11b1ce5046321f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 11 Mar 2026 14:26:32 +0000 Subject: [PATCH 3/5] Set up MkDocs (Material) + Read the Docs with versioned public docs and strict CI docs checks Co-authored-by: mbe24 <7420624+mbe24@users.noreply.github.com> --- docs/configuration.md | 8 ++++++++ docs/getting-started.md | 6 ++++++ docs/index.md | 15 ++++++++++++++- docs/requirements.txt | 1 + mkdocs.yml | 2 +- 5 files changed, 30 insertions(+), 2 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 6c4689f..b4b3b14 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -15,3 +15,11 @@ token = "ghp_your_token" ``` See the [README configuration section](https://github.com/mbe24/99problems/blob/main/README.md#configuration) for the complete configuration reference. + +## Configuration behavior + +- `--instance` selects an explicit configured instance +- If exactly one instance exists, it is auto-selected +- If multiple instances exist, `default_instance` is used when set + +Keep credentials in local config files and avoid committing tokens into version control. diff --git a/docs/getting-started.md b/docs/getting-started.md index 8623864..89190da 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -19,3 +19,9 @@ Search GitLab issues: ```bash 99problems get --platform gitlab -q "repo:veloren/veloren is:issue state:closed terrain" ``` + +Common next steps: + +- Configure a default instance in `~/.99problems` for fewer CLI flags +- Use `--format jsonl --output-mode stream` for automation pipelines +- Use the Read the Docs version selector to browse `latest`, `stable`, or a tagged release diff --git a/docs/index.md b/docs/index.md index 6ccd247..fd055c6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,7 +2,20 @@ `99problems` is an AI-native CLI for retrieving issue and pull request context across GitHub, GitLab, Jira, and Bitbucket. -Use this site for task-focused docs, and the repository README for the full project overview: +Use this site for task-focused docs, and the repository README for the full project overview. + +## What you can find here + +- Setup and day-one usage in [Getting Started](getting-started.md) +- Runtime and instance configuration in [Configuration](configuration.md) +- Versioned documentation on Read the Docs (`latest`, `stable`, and release tags) + +## Documentation boundaries + +Public documentation is built from `docs/` and published on Read the Docs. +Internal notes should stay under `docs/internal/`; they are intentionally excluded from public navigation and output. + +For complete project details and contributor workflows: - [Project README](https://github.com/mbe24/99problems/blob/main/README.md) - [Contributing Guide](https://github.com/mbe24/99problems/blob/main/CONTRIBUTING.md) diff --git a/docs/requirements.txt b/docs/requirements.txt index f2caded..bbf8384 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1 +1,2 @@ mkdocs==1.6.1 +mkdocs-material==9.6.12 diff --git a/mkdocs.yml b/mkdocs.yml index 0bb74dd..5f77185 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,7 +10,7 @@ strict: true exclude_docs: internal/** theme: - name: readthedocs + name: material nav: - Home: index.md From 215fd80760dfff4c767292758cabadb6a6bf0137 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 11 Mar 2026 14:36:52 +0000 Subject: [PATCH 4/5] docs(readme): group documentation and man pages, keep final section order Co-authored-by: mbe24 <7420624+mbe24@users.noreply.github.com> --- README.md | 50 +++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index f6af3e3..4f3d5ef 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,31 @@ This is useful for Agentic Engineering workflows and for humans doing direct inv Public docs are hosted on Read the Docs: [99problems.readthedocs.io](https://99problems.readthedocs.io/). +### Man Pages + +Generate and print root man page: + +```bash +99problems man +``` + +Generate all pages to disk: + +```bash +99problems man --output docs/man --section 1 +``` + +### Documentation Authoring + +- Public docs source lives under [`docs/`](docs/). +- Internal-only docs should live under [`docs/internal/`](docs/internal/) and are excluded from the published site. +- Validate docs locally with: + +```bash +pip install -r docs/requirements.txt +mkdocs build --strict +``` + ## Installation ```bash @@ -147,20 +172,6 @@ Note that telemetry export requires a build with the telemetry-otel feature enab - Default builds include it. - Use `--no-default-features` for telemetry-free release binaries. -## Man Pages - -Generate and print root man page: - -```bash -99problems man -``` - -Generate all pages to disk: - -```bash -99problems man --output docs/man --section 1 -``` - ## Output Modes `get` supports two orthogonal controls: @@ -212,17 +223,6 @@ If 99problems saves you time, you can support ongoing maintenance via [GitHub Sp See [CONTRIBUTING.md](CONTRIBUTING.md). -## Documentation Authoring - -- Public docs source lives under [`docs/`](docs/). -- Internal-only docs should live under [`docs/internal/`](docs/internal/) and are excluded from the published site. -- Validate docs locally with: - -```bash -pip install -r docs/requirements.txt -mkdocs build --strict -``` - ## License See [LICENSE](LICENSE). From d5eb250106700cd14e855f0dc0ded75d5cd235f1 Mon Sep 17 00:00:00 2001 From: Mikael Beyene Date: Wed, 11 Mar 2026 16:25:42 +0100 Subject: [PATCH 5/5] ci(workflows): split docs into dedicated path-filtered CI job --- .github/workflows/ci.yml | 36 +++++++++++++++++++++++++---- .gitignore | 3 +-- README.md | 49 ++++++++++++++++------------------------ 3 files changed, 52 insertions(+), 36 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 95c0494..4e9bd91 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -40,22 +40,48 @@ jobs: - name: Unit tests run: cargo test --features telemetry-otel + - name: Integration tests + if: env.GITHUB_TOKEN != '' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: cargo test --features telemetry-otel -- --include-ignored --skip jira_ --skip bitbucket_ + + docs: + name: Docs + needs: test + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + + - name: Detect docs-related changes + id: changes + uses: dorny/paths-filter@v3 + with: + filters: | + docs: + - 'docs/**' + - 'mkdocs.yml' + - '.readthedocs.yml' + - name: Set up Python + if: steps.changes.outputs.docs == 'true' uses: actions/setup-python@v6 with: python-version: "3.12" + cache: "pip" + cache-dependency-path: docs/requirements.txt - name: Install docs dependencies + if: steps.changes.outputs.docs == 'true' run: pip install -r docs/requirements.txt - name: Docs build (strict) + if: steps.changes.outputs.docs == 'true' run: mkdocs build --strict - - name: Integration tests - if: env.GITHUB_TOKEN != '' - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: cargo test --features telemetry-otel -- --include-ignored --skip jira_ --skip bitbucket_ + - name: Skip docs build (no docs changes) + if: steps.changes.outputs.docs != 'true' + run: echo "No docs-related changes detected; skipping docs build." test_no_telemetry: name: Test (no telemetry feature) diff --git a/.gitignore b/.gitignore index 4d3a9a3..edf0dfa 100644 --- a/.gitignore +++ b/.gitignore @@ -2,8 +2,7 @@ /target # Private docs (see docs/ for publishing and deployment guides) -/docs/npm-publishing.md -/docs/deployment.md +/docs/internal plan/ issue/ diff --git a/README.md b/README.md index 4f3d5ef..294b56a 100644 --- a/README.md +++ b/README.md @@ -17,35 +17,6 @@ Software tasks often depend on decisions made in earlier issues and pull request This is useful for Agentic Engineering workflows and for humans doing direct investigation in terminals or scripts. -## Documentation - -Public docs are hosted on Read the Docs: [99problems.readthedocs.io](https://99problems.readthedocs.io/). - -### Man Pages - -Generate and print root man page: - -```bash -99problems man -``` - -Generate all pages to disk: - -```bash -99problems man --output docs/man --section 1 -``` - -### Documentation Authoring - -- Public docs source lives under [`docs/`](docs/). -- Internal-only docs should live under [`docs/internal/`](docs/internal/) and are excluded from the published site. -- Validate docs locally with: - -```bash -pip install -r docs/requirements.txt -mkdocs build --strict -``` - ## Installation ```bash @@ -215,6 +186,26 @@ Use user scope by overriding path: 99problems skill init --path ~/.agents/skills ``` +## Documentation + +Project documentation is available at [99problems.readthedocs.io](https://99problems.readthedocs.io/). + +Public docs source lives in [`docs/`](docs/). Internal-only notes belong in [`docs/internal/`](docs/internal/) and are excluded from the published site. + +### Man Pages + +Generate and print root man page: + +```bash +99problems man +``` + +Generate all pages to disk: + +```bash +99problems man --output docs/man --section 1 +``` + ## Support this project If 99problems saves you time, you can support ongoing maintenance via [GitHub Sponsors](https://github.com/sponsors/mbe24) or [Ko-fi](https://ko-fi.com/mbe24).