PMIS Website Repository Documentation

Publish selected local repositories and their addon READMEs on an Odoo 18 Community website. No repositories are published automatically.

Features

A public repository index at /documentation.
Separate repository selection and publication for each website.
Markdown, reStructuredText, HTML, and plain-text READMEs in the website layout.
Links between repository overviews and individual addon READMEs, including local images and badges.
Downloads of referenced PDF manuals and signed samples in .docs/media/pdf.
Linked Markdown and reStructuredText guides in nested repository directories, rendered in the website layout with relative links, anchors, and local images.
Live local-file reads: repository updates appear on the next page request.
Fenced Markdown code blocks preserve multiline commands beneath list items.
Document headings and text provide default page titles and search descriptions.
Optimize SEO recognizes keyword phrases across document source line breaks and nonbreaking spaces without changing displayed prose or code blocks.
Website languages select translated Markdown and RST siblings, with an English fallback.
Published repository overviews and addon READMEs appear in Odoo's website sitemap. Search engines can discover linked guides through the rendered document links.

Configuration

The module depends on website and the Python packages markdown and docutils. The manifest declares these packages; it does not install them.

Install pmis_website_readme.
As a Settings administrator, open Website > Configuration and select Documentation Repositories in the Configuration menu group.
Create a record and choose a configured Odoo addon directory, a sibling Git repository, or an explicitly configured additional repository. The directory must contain a root README readable by the Odoo process.
Set its display name, URL identifier, and website. For example, select stock-accounting or pmis-beta and use that name as the URL identifier.

Add a normal website menu link to /documentation if visitors should reach it from your main navigation. Installation does not modify existing website menus.

Repositories outside the addon tree can be allowed through the system parameter pmis_website_readme.additional_source_paths under Settings > Technical > Parameters > System Parameters in developer mode. Enter absolute directory paths, separated by commas or newlines. Installation or upgrade to 18.0.1.0.1 seeds /srv/pmiverse/_pmiconfig; subsequent upgrades preserve administrator changes. These paths do not enable sibling discovery and still require explicit publication for each website.

Usage

Review the repository overview, addon READMEs, Markdown and RST documents, and linked images before making them public.
Enable Published on the repository record and save it.
Use Open Website, or visit /documentation on the selected website.
Open a repository overview and select an entry under Addon documentation to read an individual addon's README.
Disable Published or archive the record to remove public access.

Changes to local documentation files appear on the next page request; no module upgrade is required to refresh their content.

Document translations

Keep the English source and its translation in the same directory and format. For Slovene, place README_si.md beside README.md, or usage_si.rst beside usage.rst. Both Odoo language codes sl and sl_SI select the _si sibling, including websites using sl.po translations. Other languages use their base language code, for example usage_de.md for German.

Visit the original document URL using the website's language selector. If its translation is unavailable, the English source is displayed. English always uses the source. The selected document supplies the page title, search description, and references to images and PDF downloads. Relative links work from the selected file's directory. Addon listings and sitemap entries keep the original document URLs; Odoo handles the website's language prefixes.

Keep guides in the repository and link them from any README or another document. For example, use [Setup](docs/setup.md#installation) in Markdown, or this link in RST:

`Setup <docs/setup.rst#installation>`_

Both open the rendered guide on the website. Links and images resolve relative to the document containing them; parent-directory links work while remaining inside the selected repository.

Markdown inside standalone <details> disclosure blocks is rendered automatically, including local SVG badges. An explicit markdown="0" attribute keeps the block's contents unparsed. Local Markdown and RST images use the repository asset endpoint; external HTTP(S) images keep their original URLs.

Screenshots and diagrams stored under the repository's .docs/images directory are supported. For a root README or guide, use a relative link such as ![Site](.docs/images/site.png). Only referenced images in supported formats are served. PDF links under the repository's .docs/media/pdf directory are also supported, for example [Signed measurement](.docs/media/pdf/report.pdf). Downloads preserve the file bytes, including existing signature evidence. Only PDFs linked from an accessible document are served; other hidden documentation files and downloads remain excluded.

Publication and Access

Only Settings administrators can configure repositories. Backend records are restricted to their allowed companies. Public visitors can read only active, published records belonging to the current website; guessing another repository's URL does not bypass these restrictions. Unpublishing or archiving a record removes public access, including its image endpoints.

Publication includes the root README, READMEs in immediate addon directories containing __manifest__.py, and non-hidden .md and .rst files anywhere inside the repository. These documents are accessible by direct URL even when no README links to them. It does not depend on whether those addons are installed. Review all of this content before publishing. External links and images remain external browser requests; the server does not fetch them.

Local images and PDF downloads are served only when referenced by an allowed document. Paths must remain inside the selected repository, including after resolving symbolic links. Source files, arbitrary downloads, Git metadata, and other hidden directories are excluded; .badges is allowed for documentation badges, and supported images under the root .docs/images directory are allowed for screenshots and diagrams, and PDFs under the root .docs/media/pdf directory are allowed for downloads. Hidden files or subdirectories within those asset directories remain excluded, as do symbolic links resolving to other hidden content.

Rendering disables RST file inclusion and raw directives, sanitizes HTML, and removes inline styles and scripts. SVG image responses use a restrictive content security policy. Responses are not cached by browsers or proxies. A bounded in-process rendering cache is invalidated when the source file's metadata changes.

Known Limitations

Sources must already be deployed locally. Configured addon paths are eligible, along with immediate sibling Git repositories when the configured path itself has a .git directory or file. This includes non-addon repositories such as pmis-i18n-extra without adding them to Odoo's addon paths. Explicit additional paths support repositories elsewhere, such as /srv/pmiverse/_pmiconfig. Discovery does not recurse or follow sibling symlinks outside the shared parent directory. Hidden sibling directories are excluded. This addon does not clone repositories, pull Git changes, or call a Git hosting API.
README selection prefers README.md, README.rst, README.html, README.txt, then README. File names are case-sensitive.
Documents are limited to 2 MiB, local images to 5 MiB, and PDF downloads to 20 MiB.
Nested documentation supports case-sensitive .md and .rst extensions. Other formats retain the root/addon README restrictions. Source-code links and arbitrary file downloads are not exposed. Referenced PDFs in .docs/media/pdf are the sole download exception. Unsupported local links are rendered without a clickable destination.
Publication is per repository and website, not per addon or language. Translations share the source's publication status.
Original HTML page styling is replaced by the website's styling.

Development

Focused tests use the PMIVerse addon runner and a disposable test database:

/srv/pmiverse/_pmiconfig/scripts/test/run_pytest_addon.sh \
  -a /srv/pmiverse/_pmisuite18/repos/pmiverse/testing/pmis_website_readme/tests \
  -d test_pmis_website_readme -- --odoo-http -q --maxfail=1