Skip to main content
Version: 0.1.145

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.

Write the description as the document's outline: list the sections you expect. The documentation agent gives each one its own section, in that order, and 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. Repave finds its cover page, table of contents, closing page, header and footer, and shows what it found; choose Change if it guessed a page wrong.

  • A PDF template is shown exactly: its cover and closing pages appear as they are in the PDF. The header and footer are recreated 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.

Sections from your template​

The same upload also tells Repave what the document should contain. The headings in the template's body become the sections under What should it cover?, one line each, numbered as in your template:

1. Purpose and scope — about 1 page.
2. Target architecture — about 3 pages, with a picture.
2.1 Containers — a table.
3. Integrations. "List every external system and how it is called."
  • A blank template gives each heading and the line of guidance under it.
  • A previous real document gives each section's length, tables and pictures, never its text: that text describes another project. The agent writes every fact from this project.
  • A PDF gives headings and guidance only; it does not say where its tables and pictures are.
  • If you already typed what the document should cover, your text is kept, and Use the N sections from … under it swaps in the template's sections.

Edit the sections like any text before you save.

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 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.