How this site works · SmartERP Documentation

This site is the SmartERP Documentation module (smarterp_docs). It is an ordinary Odoo module: install it and SmartERP serves the documentation at /docs. It needs only Odoo's base and web, with no pip install and no website module.

The idea#

documentation/en/…md  ─┐
documentation/am/…md  ─┤   install / update /     ┌───────────────┐      ┌──────────────┐
other addons'          ├──► "Sync from Files" ───►│ database      │─────►│ /docs site   │
documentation/ folders ─┘                          │ (sections,    │      │ (public,     │
                                                   │  pages)       │      │  read-only)  │
                        edit in Odoo ─────────────►│               │      └──────────────┘
                                                   └───────────────┘

Authors write Markdown files, one per page, in a documentation folder. Files are reviewable and versioned in git like code.
On every install and update of the module, the files are read into the database as sections and pages. A menu item does the same on demand.
The site renders pages from the database, so editing in Odoo is instant and search is a database query.

Files or Odoo, your choice#

	Edit the files	Edit in Odoo
Best for	Developers, reviewed changes, translation work	A quick fix, someone who does not use git
Where	`documentation/<lang>/<section>/<page>.md`	Documentation → Pages
Takes effect	After a module update or Sync from Files	Immediately
History	git	Odoo's record tracking

Each page remembers where it came from in its Source field:

Documentation files: refreshed from disk on every update.
Edited in Odoo: you changed it in the backend, so an update never overwrites it.

Editing the title, text, summary, address or published state of a file-based page in Odoo switches it to Edited in Odoo. Reordering does not. Reset to File Version on the page brings back the file's text and reattaches it.

A page you create in Odoo with no file is never touched by a sync. A file-based page whose file is deleted is removed on the next sync, but only for the addon that provided it, and only when that addon still has a documentation folder, so a missing folder can never empty the site.

Every module can document itself#

On each sync the module also looks for a documentation folder inside every installed addon. So each SmartERP module can carry its own documentation next to its code, and it appears on the site when the module is installed. See Document your own module.

Roles#

Who	Can
Anyone, including anonymous visitors	Read published pages.
Documentation → Editor	Create, edit, publish and unpublish. See drafts on the site, labelled.

Users with Settings (administrator) access are Editors by default.

What visitors get#

A home page of sections, and a sidebar with every page.
Search as you type, and a full results page. Every word must match; a title match ranks first.
English and Amharic with a switch. A page missing in Amharic shows the English text with a notice.
An On this page list, previous and next links, breadcrumbs.
Callouts, tables, and code blocks with a Copy button.
Dark mode that follows the device, print styles, and a sitemap for search engines.
Every page works without JavaScript.

Typing in the search box shows matching pages at once. Enter shows the full list.

The search box with a word typed in it and a list of matching pages below it. — Search as you type.
Matching pages appear under the box. Press Enter to see every result.

On a wide screen a page has the sections on the left, the article in the middle and On this page on the right.

A documentation page with the list of sections on the left, the article in the middle and the On this page list on the right. — A documentation page.
The sidebar lists every section. The page you are reading is highlighted.
On this page: jump straight to a heading.
Code blocks have a Copy button.

On a phone the sidebar becomes a menu, and the whole site follows the device's light or dark setting.

The documentation on a phone, with the menu open over the page and the list of sections showing. — On a phone the sections open from the menu button. The site follows the device's light or dark setting.

Safety of what is published#

Everything an author writes is escaped: raw HTML in a Markdown file is shown as text, never run. Links and images are checked against an allow-list of schemes, so javascript: and data: links are neutralised. The renderer has automated tests for exactly these cases. Only published pages are ever served to the public.

Where things are in the module#

Path	What
`documentation/`	The pages, in Markdown.
`lib/mdrender.py`	The Markdown renderer. No Odoo imports.
`lib/docfiles.py`	Reads the `documentation` folders. No Odoo imports.
`lib/ranking.py`	Search ranking. No Odoo imports.
`lib/amharic.py`	Folds Amharic letters that sound alike, so either spelling finds the page. No Odoo imports.
`lib/assets.py`	Images by asset id: the manifest, the figures, the checks. No Odoo imports.
`models/`	Sections and pages, and the sync.
`controllers/main.py`	The public routes.
`views/`	The editor screens and the site's templates.
`static/src/`	The site's CSS and JavaScript, inlined into every page.
`static/img/`, `shots/`	The screenshots with their manifest, and the shot lists that make them.
`deploy/`	The nginx configuration for `doc.smarterp.et`.
`tests/`, `tools/`	Tests, a runner that needs no Odoo, the live preview and the screenshot tool.

The CSS and JavaScript are cached per server process: restart Odoo after changing them.