Skip to content

chore: ignore local JDK-docs corpus in docs/ (#22) #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
devops-thiago wants to merge 1 commit into
base: main
Choose a base branch
from
Open

chore: ignore local JDK-docs corpus in docs/ (#22) #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,11 @@ Thumbs.db
application-local.yml
*.env

# Local JDK-docs corpus (provisioned on the VM / mounted via Docker).
# See docs/README.md for how to obtain the corpus.
docs/*
!docs/README.md

# React Build Output
src/main/resources/static/

Expand Down
50 changes: 50 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# docs/ — JDK documentation corpus

This directory holds the **local JDK 25 documentation corpus** used as the source
material for RAG ingestion. It is **not part of the repository** and is ignored
by git (`docs/` in `.gitignore`).

## What lives here

The directory mirrors the structure of the official JDK HTML documentation
bundle:

| Path | Contents |
| --------- | ------------------------------------------ |
| `api/` | Java SE 25 API reference (javadoc HTML) |
| `specs/` | Java language / JVM specification pages |
| `legal/` | License and notices |
| `index.html` | Documentation index |

## Why it is not committed

- The bundle is ~326 MB of generated HTML — too large to commit without
permanently bloating the repository and its history.
- The corpus is provisioned locally (e.g. on the lab VM) and mounted into the
Docker stack read-only: `docker-compose.yml` mounts `./docs:/app/docs:ro`.
- Every contributor can provision the same corpus locally; see below.

## How to obtain the corpus

1. Download the JDK 25 HTML documentation bundle from the
[Oracle Java SE Downloads](https://www.oracle.com/java/technologies/downloads/)
page (the "**API docs**" / documentation archive for Java 25).
2. Extract it so that `api/`, `specs/`, `legal/` and `index.html` sit directly
under `docs/` in this repository.
3. Ingest into the RAG system:

```bash
# From the repository root
curl -X POST "http://localhost:8080/api/ingest?path=docs"
```

or ingest a single file:

```bash
curl -X POST "http://localhost:8080/api/ingest?path=docs/specs/<file>.html"
```

> **Note:** In earlier iterations of this project, `docs/` also contained
> project guides (`CHAT_UI.md`, `OBSERVABILITY.md`, `TROUBLESHOOTING.md`,
> `DOCKER.md`). Those are no longer tracked here — keep corpus content and
> project documentation separate.
Loading