Document your own module

You do not have to put every page in smarterp_docs. Any Odoo addon can carry its own documentation, and this site picks it up.

The convention#

Add a documentation folder to your addon, laid out exactly like this module's:

my_module/
  __manifest__.py
  models/ …
  documentation/
    en/
      45-my-area/
        _section.md
        10-overview.md
        20-how-to-do-x.md
    am/
      45-my-area/
        _section.md
        10-overview.md

Write the pages as described in Writing pages.

When it is picked up#

Whenever the documentation is synchronised:

• when smarterp_docs is installed or updated;
• when someone presses Documentation → Sync from Files.

Only installed addons are scanned, so documentation for a module appears when that module is installed. After installing a new module, press Sync from Files.

Sections and pages are shared by address#

A section's address (its slug) is global. That gives you two choices:

• Your own section. Pick a new address such as my-area and include a _section.md. The section and its pages belong to your addon.
• Add to an existing section. Use the same section folder name as an existing one (for example administration) and leave out _section.md. Your pages join the section, and its title, summary and position stay as they are. If your folder does include a _section.md, that file replaces the section's title, summary and position, so include it only when you mean to.

Pages are matched by section and page address. If two addons define the same page, for example administration/troubleshooting, the addon synchronised last silently wins. This module goes first, then the others in alphabetical order. Name your pages after your module's area to avoid it.

Use the number in the folder name, such as 45-, to place your section among the others.

Removing documentation#

When a page's file disappears, the page is removed on the next sync, and only if it came from that addon's folder. When an addon is uninstalled, its pages stay until its folder is gone from the addons path and a sync runs. Pages you wrote or edited in Odoo are never removed.

Documentation outside any addon#

To load a folder that is not inside an addon, such as a separate documentation repository checked out on the server, set the system parameter:

Each folder must have the same en/… and am/… layout.

A checklist for documenting a module#

• A section with a one-line summary.
• An overview: what it is for and who uses it.
• How to install it and what it needs.
• A page per task a user does, using the labels on the buttons.
• Roles: who can do what.
• Settings and scheduled actions.
• Troubleshooting with the exact text of error messages.
• A reference of models and routes.
• An Amharic version, reviewed by a fluent reader.