Skip to main content
Version: 0.1.150

Documents

Repave writes the documents your delivery process asks for — a solution architecture document, a data dictionary, a runbook — from what it knows about each project: its architecture, catalogs, database tables, decisions and features. Each document is laid out in your organization's own template: its cover page, header, footer and closing page.

Document types​

A document type says what a document is: a name, a description of what it must cover, and, optionally, a template.

  • Your organization's types are defined by an administrator in the Admin portal and apply to every project. An administrator can mark a type Must have: every project then gets that document and cannot switch it off. Must have never blocks anything else in a project.
  • A project's own types are added from the project's Documents page with Add document type, by anyone who can edit the project. They apply to that project only.

One document for the project, or one for each feature​

When you create a type, One document for chooses between The whole project — one document, such as a solution architecture document — and Each feature — a separate document for every feature, such as a functional or API specification. The choice can't be changed afterwards; to switch, create a new type.

A document for each feature is written about that feature alone: its scenarios, the APIs it exposes or calls, the tables it uses, the external systems it talks to and its processing steps. Repave updates it each time an implementation run finishes on the feature — or on the feature's module — so it describes the code as it is now; the first such run writes it if nobody has yet. You can also generate it yourself at any time. A Must have type for each feature is required on every feature of every project.

Format and where it goes​

Format is the file you get: Word (.docx), PDF, Markdown (.md) or HTML.

  • Word keeps a Word template's own cover, contents page, header, footer and closing page, and uses its heading styles. Word offers to update the table of contents when you open the file.
  • PDF is the document as Repave shows it, cover and closing page included, with the header and footer on every page.
  • Markdown is plain text with headings, lists and tables; it has no cover, header or footer. Diagrams stay as mermaid blocks, which most git hosts draw.
  • HTML is a single file that opens in any browser, with no network.

Where it goes is Repave — read and download it on the Documents page — or The codebase: the file is committed to the project's repository at the Path in the codebase you give, such as docs/specs/{feature}. {feature} becomes the feature's name, and the extension follows the format. A feature's document keeps the file it was first committed to, even if the feature is renamed later; two features with the same name get files of their own. A document in the codebase is read there, not in Repave; its row names the branch it was committed to, as a link that opens the branch on your git host.

  • A feature's document goes on the feature's branch while the feature is being worked on, so it ships in the feature's pull request.
  • For a feature in a module, it goes on the module's branch.
  • Once the feature is merged, or before it has a branch, and for a document of the whole project, it goes on a new docs branch (for example docs/functional-specification-statement-export) that Repave pushes for you to open a pull request from. Generating again adds a commit to that branch while it exists.

Repave commits only the document's own file. If a commit or push fails, the row says why and Try again generates it again. Each generation replaces the committed file, so make lasting changes in the type's description, not in the file.

What should it cover? is your brief: what you want the document to include, in your own words. It is required without a template and optional with one. The documentation agent writes "Not yet available in this project." for a section the project has no information on yet, rather than inventing it.

Templates​

Drop a .docx or .pdf into Template or example in the dialog: a blank template, or a past document of the same kind. An agent reads it, and a few seconds later the box What Repave took from it shows what it found:

Cover: page 1
Contents: page 2
End page: page 14 — "Document control and approvals"
Header: ACME Bank — Internal
Footer: Page {n} of {N} · Confidential

1. Purpose and scope — about 1 page: why the system exists, what it replaces, and what is out of scope.
2. Target architecture — about 3 pages, with a container diagram: the components, how they talk to each other, and where they run.
2.1 Containers — a table: each container, its responsibility and its technology.
  • The first five lines are the layout. They say which pages wrap every document of this type — the cover, the contents page and the closing page — and the header and footer printed on each page. Write a page as page 2, a cover of several pages as pages 1–2, and none where there is none; {n} and {N} are the page number and the page count. If a line can't be read, saving says which line and how to write it.
  • The lines after them are the outline every document of this type follows: its sections in order, how long each is, and what belongs in it. It is written in general terms: from a past document of another project the agent takes the shape, never the names, systems or numbers.
  • Edit anything that's wrong. The box is ordinary text, and what it says when you save is what is used. Where your brief asks for something the outline lacks, or disagrees with it, the brief wins.
  • You can save while the template is still being read; what Repave reads is added to the type when it is done. If reading fails, the box says why and Try again reads it again.
  • An organization's template is read with the organization's own AI keys. If none are set, the box says so, with a link to API keys in the admin portal.
  • A type saved before templates were read this way shows its layout lines; Read again reads the file to add its outline.

How the template looks around the document:

  • A PDF template is shown exactly: its cover and closing pages appear as they are in the PDF. The header and footer are printed as text.
  • A Word template carries its cover and closing page's text, tables and logos, and its heading and body styles; exact positioning may differ. Upload the PDF of your template for an exact cover.
  • With no template, Repave uses a plain layout: a title page with the document's name, the project, its version and date.

To have the project name, document name, version or date filled in on the cover, type {{project}}, {{document}}, {{version}} or {{date}} where they belong in your Word template.

The Test report template​

Test report is always first in your organization's list, marked Built in. It is not a document projects generate: it holds the template that a Daily tests run's Download PDF uses (see Testing). Open it and drop a .docx or .pdf on it, as for any template; its box holds the five layout lines only. Its cover can use {{project}}, {{document}}, {{version}} (the commit the run tested) and {{date}} (the day of the run). Page fields in its header or footer, such as "Page 3 of 66", are filled in with the report's own page numbers. A PDF template's cover and closing pages are put into the report exactly as they are. Without a template, the report uses a plain layout. Test report cannot be renamed or deleted, and it never appears on a project's Documents page.

Generating a document​

Open the project's Documents page from the side menu (under Design & Architecture). Required documents are listed first.

A type with a document for each feature is listed once, with how many features have it ("12 of 40 features"); click it to see every feature, those still to generate first. A feature's own documents are also on its Documents tab, which appears when the project has such a type.

  • Generate writes the first version; Regenerate writes a new one. The agent revises the current version rather than starting again, so sections whose facts have not changed stay as they were.
  • A whole-project document type can also regenerate automatically when a feature is merged. Several merges close together cost at most one extra run.
  • If a run fails, the row says why and the previous version stays readable. View run opens the run; Try again starts another.
  • An optional organization type can be switched off for one project with its switch. Switched-off types are listed under Switched off.

Reading and downloading​

Click a document's name to read it in Repave, inside its template: the cover, a contents list linked to each section, the document, the closing page, and the header and footer.

Download saves it in its type's format. An HTML file opens in any browser, with no network and no Repave.

A document whose type has been deleted stays readable and downloadable, marked Retired; it is no longer regenerated.