Skip to content

README.md

Latest commit

 

History

History
75 lines (56 loc) · 3.54 KB

README.md

File metadata and controls

75 lines (56 loc) · 3.54 KB
Raw

Maintaining the documentation

Help readers use or maintain Moneyflow without reconstructing its development history. Follow the documentation rules in AGENTS.md.

Where does a fact belong?

Reader question Owning document
What is Moneyflow? Overview; README routes to guides
How do I install or update it? Installation
What happens to my Python data? Moving to Go
How do I import and match Amazon purchases? Amazon
How does a provider connect, store credentials, or write changes? Its guide under guide/
What does a command accept? Command --help; CLI reference routes to it
How do components fit together now? Architecture
How do we build and publish? Development and releases

Update the owning section when behavior changes. Link to it from related pages instead of copying details. Keep exact commands, limits, failure behavior, and authorization requirements.

What gets published?

docs/site-manifest.json selects published pages. docs/zensical.toml defines current navigation. The combined site includes the homepage, walkthrough, current guides, and a frozen Python v1 archive. See website operation for layout and capture tools. README and command help must agree with the current guides.

The checked-out docs describe that revision. Mark unreleased behavior clearly; a change on main or go-port is not proof that the latest release contains it. Stable Go releases deploy docs from their tag after publication. Prereleases do not replace the public site. A manual deployment requires an explicit stable release tag.

Keep current contracts and their rationale in the architecture and user guides. Use Git history for implementation chronology. Describe unbuilt work explicitly as a limitation; an approved proposal is not evidence that a feature exists.

How do I check a change?

Use the mise tools and private temporary-directory setup in development. The website build captures synthetic TUI and web screens, so it also needs tmux and Playwright Chromium. Mise supplies Freeze. With mise activated (or each command prefixed by mise exec --), run:

make web-install
cd web && bunx playwright install --with-deps chromium && cd ..

Install tmux with your operating system's package manager if it is missing. Then run:

uv sync --project docs --frozen
make docs-check

The check lints Markdown, checks arrow-list formatting, and builds into ignored site/. docs/tools/site.ts stages only manifest-listed pages, leaves this README in the repository, and checks links in the complete built site.

After building, preview the output:

make docs-serve

Open http://127.0.0.1:8000/. Rebuild after editing.

Use the existing synthetic TUI frames or browser fixtures when a screenshot materially helps a reader. Inspect the rendered image. Do not capture private profiles or label a Python screenshot as the Go application. Generated screenshots and embedded web assets stay ignored; retained visual assets belong on a separately managed orphan-assets branch.

The documentation toolchain uses Python and uv. The application, its tests, release archives, and end users do not require Python. Do not restore the Python application for docs builds.