Skip to content

fix: errors and warnings in make livehtml #109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
pmigueld wants to merge 3 commits into
base: v2-odoo19-doc-refresh
Choose a base branch
from
Draft

fix: errors and warnings in make livehtml #109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f22e6ca
fix: errors and warnings in `make livehtml`
pmigueld Feb 3, 2026
119868c
fix: code review changes
pmigueld Feb 4, 2026
d4ee412
fix: revert mistaken g2p references
pmigueld Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/_static/caching/caching-disabled.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/standards.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/voting_flowchart.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions docs/community_and_support/i18n_l10n.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@ openspp:

# Internationalization and Localization

{term}`Internationalization` is the process of preparing an application for displaying content in languages and formats specifically to the audience.
**Internationalization** is the process of preparing an application for displaying content in languages and formats specifically to the audience.
Developers and template authors usually internationalize the application.
"i18n" is shorthand for "internationalization" (the letter "I", a run of 18 letters, the letter "N").

{term}`Localization` is the process of writing the translations of text and local formats for an application that has already been internationalized.
**Localization** is the process of writing the translations of text and local formats for an application that has already been internationalized.
Formats include dates, times, numbers, time zones, units of measure, and currency.
Translators usually localize the application.
"l10n" is shorthand for "localization" (the letter "L", a run of 10 letters, the letter "N").
Expand Down
72 changes: 71 additions & 1 deletion docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@
import sys
import logging
import yaml
import shutil
import shlex

from pathlib import Path
_logger = logging.getLogger(__name__)
Expand All @@ -29,10 +31,48 @@
# Add local extensions directory for custom Pygments lexers
sys.path.insert(0, os.path.abspath("_ext"))

try:
from sphinx.highlighting import lexers
from pygments.lexers import JavascriptLexer, JavaLexer
except Exception: # pragma: no cover - optional in minimal builds
lexers = None
else:
lexers["javascript"] = JavascriptLexer()
lexers["java"] = JavaLexer()



#=== Odoo configuration ===#

# Mock incompatible optional dependencies for autodoc BEFORE importing Odoo.
# werkzeug 2.3+ removed NumberConverter which Odoo's ir_http.py requires.
# This must be done before any Odoo imports to prevent import errors.
#
# Background: Werkzeug 2.3.0 (released 2023-04-25) removed several deprecated
# converters including NumberConverter. Odoo's ir_http.py still imports it.
# See: https://github.com/pallets/werkzeug/issues/2encoding
# https://github.com/odoo/odoo/issues/119abordar
#
# This patch can be removed once Odoo updates ir_http.py to not use NumberConverter,
# or when we pin werkzeug<2.3 in requirements.
autodoc_mock_imports = []
try:
from werkzeug.routing import NumberConverter # noqa: F401
except (ImportError, AttributeError):
# Patch werkzeug.routing to add the missing NumberConverter class
import werkzeug.routing
class NumberConverter(werkzeug.routing.BaseConverter):
"""Compatibility shim for werkzeug 2.3+ where NumberConverter was removed."""
regex = r'\d+'
num_convert = int
def __init__(self, map, fixed_digits=0, min=None, max=None, signed=False):
super().__init__(map)
self.fixed_digits = fixed_digits
self.min = min
self.max = max
self.signed = signed
werkzeug.routing.NumberConverter = NumberConverter
_logger.info("Patched werkzeug.routing.NumberConverter for Odoo compatibility")
Comment on lines 59 to 75
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

While this patch for werkzeug.routing.NumberConverter is a clever and necessary workaround for building the documentation with newer dependencies, it's worth noting that monkey-patching a library like this can be fragile. It might be beneficial to add a comment pointing to an upstream issue or discussion in Odoo or Werkzeug if one exists, to track a more permanent solution. This would help future maintainers understand the context and eventually remove the patch when it's no longer needed.


odoo_current_branch = "19.0"
# `current_version` is the Odoo version linked to the current branch.
Expand Down Expand Up @@ -130,6 +170,9 @@

#### End of Odoo

# Note: werkzeug compatibility patching is done earlier in the file,
# before Odoo imports, to ensure NumberConverter is available.


# -- Project information -----------------------------------------------------

Expand Down Expand Up @@ -187,6 +230,27 @@
"sphinx_reredirects", # URL redirects for documentation restructure
]

# Avoid graphviz warnings when dot is unavailable.
if "sphinx.ext.graphviz" in extensions and shutil.which("dot") is None:
extensions.remove("sphinx.ext.graphviz")

# Mark httpexample as parallel-safe when missing metadata.
try:
import sphinxcontrib.httpexample as _httpexample
except Exception: # pragma: no cover - optional extension
_httpexample = None
else:
_httpexample_setup = getattr(_httpexample, "setup", None)
if _httpexample_setup:
def _patched_httpexample_setup(app):
result = _httpexample_setup(app)
if isinstance(result, dict):
result.setdefault("parallel_read_safe", True)
result.setdefault("parallel_write_safe", True)
return result
return {"parallel_read_safe": True, "parallel_write_safe": True}
_httpexample.setup = _patched_httpexample_setup

# Mermaid configuration
# For offline/air-gapped builds, set MERMAID_OFFLINE=svg and install mermaid-cli:
# npm install -g @mermaid-js/mermaid-cli
Expand All @@ -195,7 +259,13 @@
mermaid_output_format = "svg" if _mermaid_offline else "raw"
mermaid_version = "11.4.0" # Pin mermaid version for stability
# Use puppeteer config for no-sandbox mode (required on Ubuntu 23.10+)
mermaid_cmd = ["mmdc", "--puppeteerConfigFile", os.path.join(os.path.dirname(__file__), "_static/puppeteer-config.json")]
mermaid_cmd = shlex.join(
[
"mmdc",
"--puppeteerConfigFile",
os.path.join(os.path.dirname(__file__), "_static/puppeteer-config.json"),
]
)
mermaid_include_elk = False # Disable ELK layout to reduce dependencies
mermaid_init_js = "" if _mermaid_offline else "mermaid.initialize({startOnLoad:true});"

Expand Down
7 changes: 3 additions & 4 deletions docs/config_guide/change_request_types/configure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -531,7 +531,6 @@ cr.action_submit() # Submit for approval

## See Also

- [Approval Workflows](../approval_workflows/) - Configure approval definitions
- [Event Data](../event_data/) - Integrate change requests with event data collection
- [API V2](../../developer_guide/api_v2/) - Create change requests via REST API
- [Studio](../studio/) - Use Configurator V2 to create custom models
- {doc}`/config_guide/event_data/index` - Integrate change requests with event data collection
- {doc}`/developer_guide/api_v2/index` - Create change requests via REST API
- {doc}`/config_guide/studio/index` - Use Configurator V2 to create custom models
24 changes: 16 additions & 8 deletions docs/config_guide/drims/alerts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,8 @@ Global defaults apply to all incidents unless overridden. These control when ale
2. Scroll to **DRIMS** section
3. Configure default thresholds

![Screenshot: DRIMS settings section](screenshots/drims_settings_defaults.png)
<!-- TODO: Add screenshot: DRIMS settings section -->
<!-- ![Screenshot: DRIMS settings section](screenshots/drims_settings_defaults.png) -->

### Global Threshold Configuration

Expand Down Expand Up @@ -97,7 +98,8 @@ Use incident-level overrides when:
3. Enable **Override Global Thresholds**
4. Set custom values

![Screenshot: Incident alert configuration tab](screenshots/incident_alert_overrides.png)
<!-- TODO: Add screenshot: Incident alert configuration tab -->
<!-- ![Screenshot: Incident alert configuration tab](screenshots/incident_alert_overrides.png) -->

| Field | Description | Example Use Case |
|-------|-------------|------------------|
Expand Down Expand Up @@ -195,7 +197,8 @@ Items with lot expiration dates within the warning period (default: 30 days).
3. Lots must have **Expiration Date** set
4. Stock must be in a **DRIMS warehouse**

![Screenshot: Product expiry configuration](screenshots/product_expiry_config.png)
<!-- TODO: Add screenshot: Product expiry configuration -->
<!-- ![Screenshot: Product expiry configuration](screenshots/product_expiry_config.png) -->

**Example Scenario:**

Expand Down Expand Up @@ -280,7 +283,8 @@ Warehouses automatically calculate health status based on active alerts:
| **Warning** | 1-2 active alerts OR capacity <30% | Orange |
| **Good** | No active alerts, adequate stock | Green |

![Screenshot: Warehouse health dashboard](screenshots/warehouse_health_status.png)
<!-- TODO: Add screenshot: Warehouse health dashboard -->
<!-- ![Screenshot: Warehouse health dashboard](screenshots/warehouse_health_status.png) -->

### Alert Dashboard

Expand All @@ -293,7 +297,8 @@ Filter by:
- **Warehouse**
- **Incident**

![Screenshot: Alert dashboard with filters](screenshots/alert_dashboard.png)
<!-- TODO: Add screenshot: Alert dashboard with filters -->
<!-- ![Screenshot: Alert dashboard with filters](screenshots/alert_dashboard.png) -->

## Responding to Alerts

Expand All @@ -307,7 +312,8 @@ When you start investigating an alert:

This removes the alert from "urgent" views but keeps it tracked.

![Screenshot: Acknowledge alert button](screenshots/alert_acknowledge.png)
<!-- TODO: Add screenshot: Acknowledge alert button -->
<!-- ![Screenshot: Acknowledge alert button](screenshots/alert_acknowledge.png) -->

### Resolving Alerts

Expand All @@ -320,7 +326,8 @@ When the underlying issue is fixed:

Resolved alerts are archived but remain in reporting for analysis.

![Screenshot: Resolve alert button](screenshots/alert_resolve.png)
<!-- TODO: Add screenshot: Resolve alert button -->
<!-- ![Screenshot: Resolve alert button](screenshots/alert_resolve.png) -->

### Alert Activity Feed

Expand Down Expand Up @@ -373,7 +380,8 @@ You cannot manually change priority. To get different priority:
3. **Resolve stale alerts** - Clean up alerts for issues that were fixed but not marked resolved
4. **Filter dashboards** - Use priority filters to focus on Critical and High alerts only

![Screenshot: Alert filters set to Critical and High](screenshots/alert_priority_filter.png)
<!-- TODO: Add screenshot: Alert filters set to Critical and High -->
<!-- ![Screenshot: Alert filters set to Critical and High](screenshots/alert_priority_filter.png) -->

### Alert Created But Condition Resolved

Expand Down
27 changes: 18 additions & 9 deletions docs/config_guide/drims/vocabularies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,8 @@ Cluster: Health
Incident: 2025 Southwest Monsoon Floods
```

![Cluster selection on request form](vocabularies/cluster_selection.png)
<!-- TODO: Add screenshot: Cluster selection on request form -->
<!-- ![Cluster selection on request form](vocabularies/cluster_selection.png) -->

```{note}
The cluster codes follow UN OCHA standards and should not be modified. If your country uses different sector names, create custom translations in **Settings → Translations** rather than changing the codes.
Expand All @@ -127,7 +128,8 @@ Priority affects:
- **Alert generation** - Overdue critical requests trigger automatic alerts
- **Approval routing** - Critical requests may bypass certain approval steps

![Priority field on request](vocabularies/priority_field.png)
<!-- TODO: Add screenshot: Priority field on request -->
<!-- ![Priority field on request](vocabularies/priority_field.png) -->

```{tip}
You can add custom priority levels (e.g., `routine` for regular stock replenishment) by adding vocabulary codes. See "Adding Custom Vocabulary Codes" below.
Expand All @@ -153,7 +155,8 @@ Condition is recorded:
- **On distribution** - When dispatching to beneficiaries
- **On return** - When items come back from field

![Item condition selection during inspection](vocabularies/condition_inspection.png)
<!-- TODO: Add screenshot: Item condition selection during inspection -->
<!-- ![Item condition selection during inspection](vocabularies/condition_inspection.png) -->

```{warning}
Items marked `damaged` or `expired` should not be distributed. DRIMS can generate alerts when such items remain in inventory beyond a threshold period.
Expand Down Expand Up @@ -184,7 +187,8 @@ This helps DRIMS:
- Route information to the right stakeholders
- Track agency roles correctly

![Coordination mode on incident](vocabularies/coordination_mode.png)
<!-- TODO: Add screenshot: Coordination mode on incident -->
<!-- ![Coordination mode on incident](vocabularies/coordination_mode.png) -->

## Organization Roles

Expand Down Expand Up @@ -215,13 +219,15 @@ You can extend vocabularies with country-specific or program-specific codes with

Go to **DRIMS → Configuration → Vocabularies**.

![Vocabularies menu](vocabularies/menu_vocabularies.png)
<!-- TODO: Add screenshot: Vocabularies menu -->
<!-- ![Vocabularies menu](vocabularies/menu_vocabularies.png) -->

### Step 2: Select the Vocabulary

Click on the vocabulary you want to extend (e.g., "Priority Levels").

![Select vocabulary](vocabularies/select_vocabulary.png)
<!-- TODO: Add screenshot: Select vocabulary -->
<!-- ![Select vocabulary](vocabularies/select_vocabulary.png) -->

### Step 3: Add a New Code

Expand All @@ -234,7 +240,8 @@ Click **Add a line** in the Codes section.
| **URI** | (auto-generated) | Leave blank - system generates |
| **Deprecated** | Unchecked | Check to hide from dropdowns |

![Add vocabulary code](vocabularies/add_code.png)
<!-- TODO: Add screenshot: Add vocabulary code -->
<!-- ![Add vocabulary code](vocabularies/add_code.png) -->

### Step 4: Save

Expand All @@ -244,7 +251,8 @@ Click **Save** to activate the new code.

Open a request form and check that the new priority level appears in the dropdown.

![New code in dropdown](vocabularies/verify_code.png)
<!-- TODO: Add screenshot: New code in dropdown -->
<!-- ![New code in dropdown](vocabularies/verify_code.png) -->

```{important}
**Code naming rules:**
Expand Down Expand Up @@ -321,7 +329,8 @@ To see all vocabularies and their codes:
2. Use the search and filters to find specific vocabularies
3. Click any vocabulary to view and edit its codes

![Vocabulary list](vocabularies/vocabulary_list.png)
<!-- TODO: Add screenshot: Vocabulary list -->
<!-- ![Vocabulary list](vocabularies/vocabulary_list.png) -->

## Are You Stuck?

Expand Down
12 changes: 8 additions & 4 deletions docs/config_guide/drims/warehouses.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,13 +52,15 @@ Before a warehouse can be used for disaster response operations, it must be enab

1. Navigate to **DRIMS → Inventory → Warehouses**

![Screenshot placeholder: DRIMS inventory menu](warehouses/nav_warehouses.png)
<!-- TODO: Add screenshot: DRIMS inventory menu -->
<!-- ![Screenshot placeholder: DRIMS inventory menu](warehouses/nav_warehouses.png) -->

2. Select an existing warehouse or create a new one using the **New** button

3. In the warehouse form, check the **DRIMS Warehouse** checkbox

![Screenshot placeholder: DRIMS warehouse checkbox](warehouses/enable_drims.png)
<!-- TODO: Add screenshot: DRIMS warehouse checkbox -->
<!-- ![Screenshot placeholder: DRIMS warehouse checkbox](warehouses/enable_drims.png) -->

4. Configure the DRIMS-specific fields (see next section)

Expand All @@ -75,7 +77,8 @@ Once a warehouse is DRIMS-enabled, configure these fields:
| **Area** | Dropdown | Recommended | Geographic location from the area hierarchy |
| **Linked Incidents** | Multi-select | Optional | Specific disasters this warehouse serves |

![Screenshot placeholder: DRIMS warehouse configuration form](warehouses/config_form.png)
<!-- TODO: Add screenshot: DRIMS warehouse configuration form -->
<!-- ![Screenshot placeholder: DRIMS warehouse configuration form](warehouses/config_form.png) -->

### Field Details

Expand Down Expand Up @@ -124,7 +127,8 @@ You can associate warehouses with specific disaster incidents in two ways:
4. Select warehouses from the list
5. Save the incident

![Screenshot placeholder: Incident warehouses tab](warehouses/incident_link.png)
<!-- TODO: Add screenshot: Incident warehouses tab -->
<!-- ![Screenshot placeholder: Incident warehouses tab](warehouses/incident_link.png) -->

**When to link warehouses to incidents:**

Expand Down
12 changes: 8 additions & 4 deletions docs/config_guide/role_configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,8 @@ If your deployment includes the Roles feature, OpenSPP shows a banner on the use
1. Go to **Settings → Users & Companies → Users** and click **Create**.
2. Fill in name and email/login, then **Save**.

![User creation form](/_images/en-us/config-guide/role-configuration/01-user-creation-form.png)
<!-- TODO: Add screenshot: User creation form -->
<!-- ![User creation form](/_images/en-us/config-guide/role-configuration/01-user-creation-form.png) -->

### Assign roles (recommended)

Expand All @@ -40,7 +41,8 @@ If your deployment includes the Roles feature, OpenSPP shows a banner on the use
- **From / To** (optional): time-bound access
- **Enabled**: turn the role on/off

![Roles tab on the user form with one enabled role line](/_images/en-us/config-guide/role-configuration/02-roles-tab-with-role-line.png)
<!-- TODO: Add screenshot: Roles tab on the user form with one enabled role line -->
<!-- ![Roles tab on the user form with one enabled role line](/_images/en-us/config-guide/role-configuration/02-roles-tab-with-role-line.png) -->

### Restrict access to an area (local roles)

Expand All @@ -50,7 +52,8 @@ If the Areas module is installed, roles can be assigned as **local** and scoped
- OpenSPP computes the user's "Center Areas" based on local role assignments.
- Record rules in domain modules can use the user's center areas to restrict which records are visible.

![Role line with a selected Center Area and the computed Center Areas field on the user](/_images/en-us/config-guide/role-configuration/03-local-role-center-area.png)
<!-- TODO: Add screenshot: Role line with a selected Center Area and the computed Center Areas field on the user -->
<!-- ![Role line with a selected Center Area and the computed Center Areas field on the user](/_images/en-us/config-guide/role-configuration/03-local-role-center-area.png) -->

### Remove or suspend access

Expand All @@ -72,7 +75,8 @@ You can create new roles that combine multiple groups:
2. Create a role and add the implied groups it should grant.
3. Assign the role to users on the user form.

![Settings → Users & Companies → Roles for custom role configuration](/_images/en-us/config-guide/role-configuration/04-custom-roles-settings.png)
<!-- TODO: Add screenshot: Settings → Users & Companies → Roles for custom role configuration -->
<!-- ![Settings → Users & Companies → Roles for custom role configuration](/_images/en-us/config-guide/role-configuration/04-custom-roles-settings.png) -->

```{note}
For long-term maintainability, prefer implementing new privileges/groups/roles in an OpenSPP module (XML/CSV) rather than changing core security definitions from the UI.
Expand Down
Loading