### Combined OpenSPP Docker Setup Commands

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/development_setup.md

An example of executing multiple `invoke` commands sequentially in a single line to streamline the setup process for a new OpenSPP Docker environment.

```bash
invoke develop img-pull img-build git-aggregate resetdb start
```

--------------------------------

### Initialize OpenSPP Development Environment with Docker

Source: https://github.com/openspp/documentation/blob/main/docs/getting_started/installation_guide.md

This command sequence clones the OpenSPP Docker repository and initializes the development environment. It includes pulling and building necessary Docker images, aggregating Git submodules, resetting the database, and starting all services required for local development.

```bash
$ git clone git@github.com:openspp/openspp-docker.git
$ invoke develop img-pull img-build git-aggregate resetdb start
```

--------------------------------

### Activate Odoo Service

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/development_setup.md

Starts the Odoo application service, making it accessible for development and testing.

```bash
invoke start
```

--------------------------------

### Start Odoo for Subsequent Runs

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This command starts the Odoo server for regular operation after the initial database setup. It connects to the 'odoo' database using the specified user, password, host, port, workers, gevent port, proxy mode, and custom configuration file. Unlike the initial start, it omits the `-i` parameter, preventing re-initialization of modules and speeding up startup.

```bash
python odoo/odoo-bin -d odoo -r odoo -w YOUR_PASSWORD --db_host=127.0.0.1 -p 17069 --workers=4 --gevent-port=8072 --proxy-mode --config=$HOME/odoo.cfg
```

--------------------------------

### Clone OpenSPP Documentation and Build HTML

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/setup-build.md

Commands to clone the OpenSPP Documentation repository from GitHub, navigate into its directory, and build the initial HTML documentation using the `make html` command. This process also handles Python virtual environment setup and dependency installation.

```shell
git clone https://github.com/OpenSPP/documentation.git
cd documentation
make html
```

--------------------------------

### Setup VSCode Development Environment

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/development_setup.md

Executes the 'develop' command using Invoke to configure the Visual Studio Code development environment for OpenSPP.

```bash
invoke develop
```

--------------------------------

### Run Live Preview of Documentation

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/authors.md

Use `sphinx-autobuild` to view changes in the browser while editing documentation. This command starts a local server, typically accessible at http://127.0.0.1:8000/, for live preview.

```shell
make livehtml
```

--------------------------------

### Generate New Database (With Demo Data)

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/development_setup.md

Resets or creates a new database instance, including pre-populated demo data, useful for testing functionalities with sample content.

```bash
invoke resetdb --demo
```

--------------------------------

### Generate New Database (No Demo Data)

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/development_setup.md

Resets or creates a new database instance without any pre-populated demo data, providing a clean slate for development.

```bash
invoke resetdb
```

--------------------------------

### Start Odoo with Initial Database Initialization

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This command initiates the Odoo server for the first time, connecting to the 'odoo' database. It specifies the database name, user, password, host, port, number of workers, gevent port, proxy mode, and uses a custom configuration file. The `-i base,queue_job` parameter ensures that the base Odoo modules and the queue job module are installed and initialized during this first run.

```bash
python odoo/odoo-bin -d odoo -r odoo -w YOUR_PASSWORD --db_host=127.0.0.1 -p 17069 --workers=4 --gevent-port=8072 --proxy-mode --config=$HOME/odoo.cfg -i base,queue_job
```

--------------------------------

### Build Docker Images Locally

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/development_setup.md

Constructs Docker images from source locally, useful for custom modifications or when remote images are not desired.

```bash
invoke img-build
```

--------------------------------

### Install PostgreSQL and PostGIS on Ubuntu

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This command installs PostgreSQL, its client, and the PostGIS extension on an Ubuntu system using the 'apt' package manager. These are essential prerequisites for OpenSPP's database requirements.

```bash
sudo apt update;
sudo apt install postgresql postgresql-client postgis;
```

--------------------------------

### Install Graphviz on macOS and Ubuntu

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/setup-build.md

Commands to install Graphviz, a graph visualization software, on different operating systems. Graphviz is required for rendering diagrams within the documentation.

```shell
brew install graphviz
```

```shell
sudo apt-get install graphviz
```

--------------------------------

### Install OpenSPP Module Python Dependencies

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

These commands install the necessary Python packages for the OpenSPP modules. It first installs `rlPyCairo` and then proceeds to install all other dependencies listed in the `openspp-requirements.txt` file, ensuring all module requirements are met.

```bash
pip install rlPyCairo
pip install -r openspp-modules/openspp-requirements.txt
```

--------------------------------

### Retrieve Docker Images

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/development_setup.md

Pulls Docker images as specified in the project's .yaml configuration files, ensuring all necessary container images are available locally.

```bash
invoke img-pull
```

--------------------------------

### Build or Pull Docker Images Conditionally

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/development_setup.md

Builds Docker images locally if necessary, or pulls them from a remote repository if a local build is not required or preferred.

```bash
invoke img-build --pull
```

--------------------------------

### Build OpenSPP Documentation Locally

Source: https://github.com/openspp/documentation/blob/main/docs/community_and_support/how_to_contribute_to_the_project.md

Provides a sequence of commands to navigate to the documentation directory, install necessary Python dependencies from `requirements.txt`, and build the HTML documentation using Sphinx's `make html` command. This process requires Python 3.10 and a virtual environment.

```bash
cd docs
pip install -r requirements.txt
make html
```

--------------------------------

### Start React Development Server (Bash)

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/beneficiary_keycloak.md

This command starts the local development server for the React application. Once running, the application can be accessed in a web browser, typically at `http://localhost:3000`.

```bash
npm start
```

--------------------------------

### Install Odoo in Python Virtual Environment

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This sequence of commands sets up Odoo within a dedicated Python virtual environment using Pyenv. It installs a specific Python version (3.10.14), creates and activates a virtual environment named 'openspp', upgrades pip, clones the Odoo 17.0 repository, installs Odoo in editable mode, and finally installs all its Python dependencies.

```bash
pyenv install 3.10.14
pyenv virtualenv 3.10.14 openspp
pyenv activate openspp
pip install --upgrade pip
git clone --single-branch -b 17.0 --depth 1 https://github.com/odoo/odoo.git
pip install --editable ./odoo
pip install -r odoo/requirements.txt
```

--------------------------------

### MyST Markdown Configuration for HTML Meta Tags

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/authors.md

Example of configuring HTML and Open Graph metadata within a MyST Markdown document's topmatter. This setup uses the `html_meta` directive to define `description`, `og:description`, `og:title`, and `keywords` for SEO and social media previews. Note that `description` and `og:description` content should be identical.

```md
---
myst:
  html_meta:
    "description": "Authors' guide to writing OpenSPP Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors."
    "property=og:description": "Authors' guide to writing OpenSPP Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors."
    "property=og:title": "Authors Guide"
    "keywords": "OpenSPP, Documentation, SEO, meta, Vale, spell, grammar, style, check, linkcheck, lexer"
---
```

--------------------------------

### Install Pyenv Build Dependencies and Pyenv

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This snippet installs essential build tools and libraries required for compiling different Python versions using Pyenv on a Linux system (e.g., Ubuntu). Following the dependency installation, it downloads and installs Pyenv itself, then configures the necessary shell environment variables in `.bashrc` and `.profile` for Pyenv to function correctly.

```bash
sudo apt install build-essential libssl-dev zlib1g-dev libbz2-dev \
libreadline-dev libsqlite3-dev curl git libncursesw5-dev xz-utils tk-dev \
libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

curl https://pyenv.run | bash
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> $HOME/.bashrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> $HOME/.bashrc
echo 'eval "$(pyenv virtualenv-init -)"' >> $HOME/.profile
```

--------------------------------

### Install Odoo Module Python Dependencies from `requirements.txt`

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/troubleshooting.md

Resolves 'Missing Python library' errors during Odoo module installation by executing `pip install -r requirements.txt`. This command installs all required Python libraries defined in the project's dependency file, ensuring a complete and functional Odoo environment.

```Shell
pip install -r requirements.txt
```

--------------------------------

### Install Keycloak.js Adapter (npm/Bash)

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/beneficiary_keycloak.md

This command installs the `keycloak-js` package, which is the official JavaScript adapter for Keycloak, enabling client-side applications to interact with the Keycloak server for authentication.

```bash
npm install keycloak-js
```

--------------------------------

### Install wkhtmltopdf for PDF Generation

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This snippet first downloads the `wkhtmltopdf` Debian package from its GitHub releases. It then uses `apt` to install the downloaded package, along with its dependencies, which is crucial for Odoo's ability to generate PDF reports.

```bash
curl -o wkhtmltox.deb -sSL https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.jammy_amd64.deb

sudo apt install -y --no-install-recommends ./wkhtmltox.deb
```

--------------------------------

### Install Nginx and UFW, Configure Basic Firewall Rules

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This sequence of commands installs Nginx as a web proxy for WebSockets and UFW (Uncomplicated Firewall) for easier network configuration. It enables UFW, allows Nginx HTTP traffic, opens a specific TCP port (8072), reloads the firewall, and prepares the Nginx configuration file structure.

```bash
sudo apt install nginx ufw
sudo ufw enable
sudo ufw allow 'Nginx HTTP'
sudo ufw allow 8072/tcp
sudo ufw reload
touch /etc/nginx/sites-available/openspp.conf
ln -s /etc/nginx/sites-available/openspp.conf /etc/nginx/sites-enabled/openspp.conf
```

--------------------------------

### Install Pyenv Virtualenv Plugin

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This command clones the `pyenv-virtualenv` plugin repository into the Pyenv plugins directory. This plugin extends Pyenv's functionality, allowing users to easily create and manage Python virtual environments.

```bash
git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv
```

--------------------------------

### Example JSON Output for Partner Data

Source: https://github.com/openspp/documentation/blob/main/docs/technical_reference/external_api.rst

An example of JSON data representing a partner record, typically used for demonstration or testing purposes.

```json
[[78, "Newer partner"]]
```

--------------------------------

### Install Odoo Linux System Dependencies

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This command installs several critical system libraries required for Odoo to function correctly on a Debian/Ubuntu-based system. These include development files for LDAP, SASL, PostgreSQL, and the Cairo graphics library, which are essential for various Odoo features.

```bash
sudo apt install libldap2-dev libsasl2-dev libpq-dev libcairo2-dev
```

--------------------------------

### Build OpenSPP Documentation

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/admins.md

Executes the `make html` command to build the OpenSPP documentation. This process typically involves generating symlinks to external documentation and compiling all project documentation into HTML format.

```shell
make html
```

--------------------------------

### Validate Syntax Highlighting: Sphinx Warning Example

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/authors.md

This console output snippet demonstrates a common Sphinx warning indicating that a code block could not be properly lexed as 'python', leading to skipped highlighting. This typically occurs due to invalid syntax within the code block, such as using ellipses for omitted code or comments in JSON.

```console
/OpenSPP/documentation/classic-ui/bodyclasses.md:10: WARNING: Could not lex literal_block as "python". Highlighting skipped.
```

--------------------------------

### Validate Documentation Markup Syntax

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/authors.md

To validate the markup syntax of the documentation, run this command. After execution, the generated HTML output can be viewed by opening `_build/html/index.html` in a web browser.

```shell
make html
```

--------------------------------

### Python F-string Example with Line Highlighting

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/myst-reference.md

Provides a Python code example demonstrating the use of f-strings for formatted output. The snippet also shows how to specify line numbering and highlight particular lines within a code block for emphasis.

```python
a = 2
print("my 1st line")
print(f"my {a}nd line")
```

--------------------------------

### Perform American English Spelling, Grammar, and Style Checks with Vale

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/authors.md

This command runs `Vale` to enforce American English spelling, grammar, and style guidelines, configured via `Makefile` and `.vale.ini`. It helps maintain consistency with the Microsoft Writing Style Guide.

```shell
make vale
```

--------------------------------

### Run Vale Style and Grammar Check

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/setup-build.md

Command to execute Vale, a linter for narrative text, to check the documentation for American English spelling, grammar, syntax, and adherence to the Microsoft Developer Style Guide. Suggestions and issues are displayed directly on the console.

```shell
make vale
```

--------------------------------

### Programmatically Create Custom Model and Field

Source: https://github.com/openspp/documentation/blob/main/docs/technical_reference/external_api.rst

Code examples demonstrating how to create a new custom model (`x_custom`) and add a new manual field (`x_name`) to it using the OpenSPP API. The examples also show how to create and read a record in the newly defined custom model.

```python
id = models.execute_kw(db, uid, password, 'ir.model', 'create', [{
    'name': "Custom Model",
    'model': "x_custom",
    'state': 'manual',
}])
models.execute_kw(db, uid, password, 'ir.model.fields', 'create', [{
    'model_id': id,
    'name': 'x_name',
    'ttype': 'char',
    'state': 'manual',
    'required': True,
}])
record_id = models.execute_kw(db, uid, password, 'x_custom', 'create', [{'x_name': "test record"}])
models.execute_kw(db, uid, password, 'x_custom', 'read', [[record_id]])
```

```php
$id = $models->execute_kw($db, $uid, $password, 'ir.model', 'create', array(array(
    'name' => "Custom Model",
    'model' => 'x_custom',
    'state' => 'manual'
)));
$models->execute_kw($db, $uid, $password, 'ir.model.fields', 'create', array(array(
    'model_id' => $id,
    'name' => 'x_name',
    'ttype' => 'char',
    'state' => 'manual',
    'required' => true
)));
$record_id = $models->execute_kw($db, $uid, $password, 'x_custom', 'create', array(array('x_name' => "test record")));
$models->execute_kw($db, $uid, $password, 'x_custom', 'read', array(array($record_id)));
```

```ruby
id = models.execute_kw(db, uid, password, 'ir.model', 'create', [{
    name: "Custom Model",
    model: "x_custom",
    state: 'manual'
}])
models.execute_kw(db, uid, password, 'ir.model.fields', 'create', [{
    model_id: id,
    name: "x_name",
    ttype: "char",
    state: "manual",
    required: true
}])
record_id = models.execute_kw(db, uid, password, 'x_custom', 'create', [{x_name: "test record"}])
models.execute_kw(db, uid, password, 'x_custom', 'read', [[record_id]])
```

```java
final Integer id = (Integer)models.execute(
    "execute_kw", asList(
        db, uid, password,
        "ir.model", "create",
        asList(new HashMap<String, Object>() {{
            put("name", "Custom Model");
            put("model", "x_custom");
            put("state", "manual");
        }})
));
models.execute(
    "execute_kw", asList(
```

--------------------------------

### Add Git Submodule for External Package

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/admins.md

Adds an external package repository as a git submodule within the `openspp/documentation` project. This command links a GitHub repository to a local subdirectory, allowing its content to be managed as part of the main project.

```shell
git submodule add git@github.com:openspp/my_package.git submodules/my_package
```

--------------------------------

### Validate Syntax Highlighting: Build Sphinx Documentation

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/authors.md

This shell command is used to build the Sphinx documentation, which is the primary method for validating syntax highlighting. Running `make html` will display any Sphinx warnings in the console, allowing authors to identify and correct issues with lexer selection or code block syntax.

```shell
make html
```

--------------------------------

### Initialize XML-RPC Client and Retrieve Connection Info

Source: https://github.com/openspp/documentation/blob/main/docs/technical_reference/external_api.rst

This snippet initializes an Apache XML-RPC client and connects to the OpenSPP 'start' endpoint. It retrieves essential connection details such as host URL, database name, username, and password, which are required for subsequent API calls.

```Java
final XmlRpcClient client = new XmlRpcClient();

final XmlRpcClientConfigImpl start_config = new XmlRpcClientConfigImpl();
start_config.setServerURL(new URL("https://demo.openspp.org/start"));
final Map<String, String> info = (Map<String, String>)client.execute(
    start_config, "start", emptyList());

final String url = info.get("host"),
              db = info.get("database"),
        username = info.get("user"),
        password = info.get("password");
```

--------------------------------

### OpenSPP: Updating Existing Records via Data Import

Source: https://github.com/openspp/documentation/blob/main/docs/howto/user_guides/import_registrant_data.md

Comprehensive guide for updating existing individual or group records in OpenSPP. Covers the full lifecycle from exporting data to obtain unique IDs, preparing the file, navigating the import interface, validating, and finally importing the updated records.

```APIDOC
Process: Update Existing Individual or Group Records
  Purpose: Modify existing data in OpenSPP.
  Prerequisite: Export existing records to obtain unique 'id' for each record.

  Steps:
    1. Export Registrant Data:
      - Action: Follow steps in 'Export Registrant Data' guide.
      - Output: Downloaded file containing existing records with 'id' column.
    2. Prepare Exported File:
      - Action: Open the downloaded file.
      - Requirement: Keep the 'id' column intact (serves as record identifier).
      - Action: Replace values in other headers to be updated.
      - Data Handling Notes:
        - Empty Cell: Overwrites corresponding OpenSPP field with a blank value.
        - Date Format: Must be YYYY-MM-DD.
        - Numeric Values:
          - Issue: Formatting errors (e.g., if not treated as text).
          - Resolution: Format entire column to 'Text' in spreadsheet software before inputting numeric values.
    3. Initiate Import in OpenSPP:
      - Navigation: Registry -> Individuals/Groups -> Favorites -> Import records.
      - Action: Locate and 'Upload file'.
      - Option: Check 'Import in the background' for large files.
    4. Validate Import File:
      - Action: Click 'Test'.
      - Expected Success: Message 'Everything seems valid' displayed.
      - Expected Failure: Error message with directions (refer to 'Error handling' section).
    5. Execute Import:
      - Action: Click 'Import'.
      - Notification: Displays number of successfully imported records.
    6. Verify Uploaded Records:
      - Navigation: Filters -> Last updated on -> Apply.
      - Verification: Newly created/updated records should display in the registry list.
```

--------------------------------

### Validate External and Internal Links

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/authors.md

This command uses Sphinx's `linkcheck` builder to automatically validate all external and internal links in the documentation. Broken links are reported in `_build/linkcheck/output.txt`.

```shell
make linkcheck
```

--------------------------------

### Search and Read Records with search_read

Source: https://github.com/openspp/documentation/blob/main/docs/technical_reference/external_api.rst

This example shows how to use the `search_read` method, which combines the functionality of `search` and `read` into a single call. It filters for company records (`is_company = True`), retrieves specific fields ('name', 'country_id', 'comment'), and limits the results to 5 records.

```python
models.execute_kw(db, uid, password, 'res.partner', 'search_read', [[['is_company', '=', True]]], {'fields': ['name', 'country_id', 'comment'], 'limit': 5})
```

```ruby
models.execute_kw(db, uid, password, 'res.partner', 'search_read', [[['is_company', '=', true]]], {fields: %w(name country_id comment), limit: 5})
```

```php
$models->execute_kw($db, $uid, $password, 'res.partner', 'search_read', array(array(array('is_company', '=', true))), array('fields'=>array('name', 'country_id', 'comment'), 'limit'=>5));
```

--------------------------------

### Create Custom Model and Retrieve Built-in Fields

Source: https://github.com/openspp/documentation/blob/main/docs/technical_reference/external_api.rst

Illustrates how to dynamically create a new custom model (`x_custom_model`) via `ir.model` and then retrieve its default built-in fields using `fields_get`. Custom models must start with `x_` and have `state` set to `manual`.

```python
models.execute_kw(db, uid, password, 'ir.model', 'create', [{
    'name': "Custom Model",
    'model': "x_custom_model",
    'state': 'manual'
}])
models.execute_kw(db, uid, password, 'x_custom_model', 'fields_get', [], {'attributes': ['string', 'help', 'type']})
```

```php
$models->execute_kw($db, $uid, $password, 'ir.model', 'create', array(array(
    'name' => "Custom Model",
    'model' => 'x_custom_model',
    'state' => 'manual'
)));
$models->execute_kw($db, $uid, $password, 'x_custom_model', 'fields_get', array(), array('attributes' => array('string', 'help', 'type')));
```

```ruby
models.execute_kw(db, uid, password, 'ir.model', 'create', [{
    name: "Custom Model",
    model: 'x_custom_model',
    state: 'manual'
}])
fields = models.execute_kw(db, uid, password, 'x_custom_model', 'fields_get', [], {attributes: %w(string help type)})
```

```java
models.execute(
    "execute_kw", asList(
        db, uid, password,
        "ir.model", "create",
        asList(new HashMap<String, Object>() {{
            put("name", "Custom Model");
            put("model", "x_custom_model");
            put("state", "manual");
        }})
));
final Object fields = models.execute(
    "execute_kw", asList(
        db, uid, password,
        "x_custom_model", "fields_get",
        emptyList(),
```

--------------------------------

### Generated HTML Meta Tags from MyST Configuration

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/authors.md

The resulting HTML `<meta>` tags generated in the `<head>` section of a web page, demonstrating how the MyST Markdown `html_meta` configuration is rendered. These tags are crucial for search engine optimization and rich social media previews.

```html
<meta content="Authors' guide to writing OpenSPP Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors." name="description" />
<meta content="Authors' guide to writing OpenSPP Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors." property="og:description" />
<meta content="Authors Guide" property="og:title" />
<meta content="OpenSPP, Documentation, SEO, meta, Vale, spell, grammar, style, check, linkcheck, lexer" name="keywords" />
```

--------------------------------

### Install Specific Python Libraries for Odoo Modules

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/troubleshooting.md

Addresses 'Missing Python library' errors by installing individual Python libraries explicitly mentioned in the error message using pip. For example, if the error specifies 'y' and 'z', the command would be `pip install y z`. This method is useful for targeted dependency resolution.

```Shell
pip install library_name
```

--------------------------------

### Define OpenSPP Custom Area Module Dependencies

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/custom_areas.md

This Python code snippet defines the dependencies for a new OpenSPP custom area module, typically found in a `__manifest__.py` file. It specifies that the module depends on 'spp_area', ensuring that the base area module is installed before this custom module.

```python
 "depends": [
       "spp_area",
   ],
")
```

--------------------------------

### Display Available Documentation Builds

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/setup-build.md

Command to list the most frequently used build targets defined in the project's `Makefile`. This provides a quick overview of common documentation generation and checking options.

```shell
make help
```

--------------------------------

### Clone OpenSPP Modules Repository

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This command clones the `openspp-modules` GitHub repository, specifically targeting the 17.0 branch. This repository contains custom modules and functionalities specific to the OpenSPP project.

```bash
git clone --single-branch -b 17.0 https://github.com/OpenSPP/openspp-modules.git
```

--------------------------------

### Test and Restart Nginx Service

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

These commands are used to validate the Nginx configuration for syntax errors using `nginx -t` and then restart the Nginx service to apply any changes. This ensures that new configurations are loaded correctly without service interruption.

```bash
sudo nginx -t
sudo servicectl restart nginx
```

--------------------------------

### Create React Application with npx (Bash)

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/beneficiary_keycloak.md

This command initializes a new React project named 'kc-react-app' using `create-react-app`. It sets up the basic project structure and dependencies, then navigates into the newly created directory.

```bash
npx create-react-app kc-react-app
cd kc-react-app
```

--------------------------------

### Build HTML Documentation

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/setup-build.md

Command to generate the static HTML version of the OpenSPP documentation. After execution, the generated documentation can be viewed by opening the `_build/html/index.html` file in a web browser.

```shell
make html
```

--------------------------------

### Define New REST API GET Endpoint for Area Data in Odoo XML

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/rest_api.md

This XML code defines a new record for the 'spp_api.path' model, effectively creating a custom REST API GET endpoint named 'Area'. It configures the endpoint by linking it to the 'spp_area' Odoo model, specifying the API namespace, providing a description, setting the HTTP method to 'get', and listing the specific fields from the 'spp_area' model that should be exposed through this API endpoint.

```xml
   <record id="area_path" model="spp_api.path">
       <field name="name">Area</field>
       <field name="model_id" ref="spp_area.model_spp_area" />
       <field name="namespace_id" ref="spp_api_records.spp_api_namespace" />
       <field name="description">GET Area</field>
       <field name="method">get</field>
       <field
           name="field_ids"
           eval="[(
           6, 0, [
               ref('spp_area.field_spp_area__parent_id'),
               ref('spp_area.field_spp_area__name'),
               ref('spp_area.field_spp_area__draft_name'),
               ref('spp_area.field_spp_area__code'),
           ]
       )]"
       />
   </record>
```

--------------------------------

### Configure Nginx Gzip Compression and Client Settings

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This Nginx configuration snippet enables gzip compression for various content types (text, XML, JSON, JavaScript) to improve web performance. It also defines client body buffer sizes, maximum body size, enables sendfile, and sets timeouts for sending data and keeping connections alive.

```nginx
gzip_types text/css text/less text/plain text/xml application/xml application/json application/javascript;
gzip on;

client_body_in_file_only clean;
client_body_buffer_size 32K;
client_max_body_size 500M;
sendfile on;
send_timeout 600s;
keepalive_timeout 300;
}
```

--------------------------------

### Restart PostgreSQL Service

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This command restarts the PostgreSQL database service. It is necessary to apply any recent configuration changes, such as new user permissions, database creations, or extension enabling, ensuring they take effect.

```bash
sudo systemctl restart postgresql
```

--------------------------------

### Build Live HTML Documentation with Reload

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/setup-build.md

Command to build the Sphinx documentation with live-reloading capabilities. This allows developers to see changes in the browser automatically as source files are modified, streamlining the documentation development workflow.

```shell
make livehtml
```

--------------------------------

### Update Existing Records in Odoo res.partner Model

Source: https://github.com/openspp/documentation/blob/main/docs/technical_reference/external_api.rst

Shows how to update existing records in the `res.partner` model using the `write` method. It takes a list of record IDs and a mapping of updated fields. The example also includes a subsequent `name_get` call to verify the change. Examples are given for Python, Ruby, PHP, and Java.

```python
models.execute_kw(db, uid, password, 'res.partner', 'write', [[id], {'name': "Newer partner"}])
# get record name after having changed it
models.execute_kw(db, uid, password, 'res.partner', 'name_get', [[id]])
```

```ruby
models.execute_kw(db, uid, password, 'res.partner', 'write', [[id], {name: "Newer partner"}])
# get record name after having changed it
models.execute_kw(db, uid, password, 'res.partner', 'name_get', [[id]])
```

```php
$models->execute_kw($db, $uid, $password, 'res.partner', 'write', array(array($id), array('name'=>"Newer partner")));
// get record name after having changed it
$models->execute_kw($db, $uid, $password,
    'res.partner', 'name_get', array(array($id)));
```

```java
models.execute("execute_kw", asList(
    db, uid, password,
    "res.partner", "write",
    asList(
        asList(id),
        new HashMap() {{ put("name", "Newer Partner"); }}
    )
));
// get record name after having changed it
asList((Object[])models.execute("execute_kw", asList(
    db, uid, password,
    "res.partner", "name_get",
    asList(asList(id))
)));
```

--------------------------------

### Check Documentation External Links

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/setup-build.md

Command to perform a comprehensive check of all external links within the documentation. The results, including any broken links, are outputted to `_build/linkcheck/output.txt` for review.

```shell
make linkcheck
```

--------------------------------

### Link to External Page in MyST

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/myst-reference.md

Provides an example of a standard Markdown link to an external URL. This is used for referencing external resources outside the current documentation.

```Markdown
Use [Shimmer](http://example.com) for cleaner whiter teeth.
```

--------------------------------

### Enable PostGIS Extensions in PostgreSQL

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

These commands enable the PostGIS and PostGIS Topology extensions within the 'odoo' database. PostGIS provides powerful geospatial capabilities, allowing Odoo to store, query, and analyze geographic information.

```bash
sudo -u postgres psql -d odoo -c "CREATE EXTENSION postgis;"
sudo -u postgres psql -d odoo -c "CREATE EXTENSION postgis_topology;"
```

--------------------------------

### Initialize Keycloak Configuration (JavaScript)

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/beneficiary_keycloak.md

This JavaScript code creates a new Keycloak instance, configuring it with the necessary server details such as the authentication server URL, realm, client ID, and redirect URI. These values should be substituted from the downloaded Keycloak adapter configuration.

```javascript
import Keycloak from "keycloak-js";

const keycloak = new Keycloak({
  url: "http://localhost:8080/", //auth-server-url
  realm: "OpenSPP", //realm
  clientId: "user-portal", // resource
  redirectUri: "http://localhost:3000", // local development redirect uri
});

export default keycloak;
```

--------------------------------

### Escape Literal Backticks Inline in MyST

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/myst-reference.md

Demonstrates how to display literal backticks inline within MyST markdown, useful for showing syntax examples or specific terms without rendering them as code blocks.

```MyST
This is MyST syntax for term `React `
```

--------------------------------

### Exclude a URL from Link Validation

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/authors.md

To prevent the `linkcheck` builder from validating a specific URL, wrap it in single backticks within the Markdown content. This is useful for private, local, or intentionally invalid links that should not cause `linkcheck` failures.

```markdown
Visit the URL `http://www.example.com` for an example.
```

--------------------------------

### Check Nginx Service Status

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This command checks the current operational status of the Nginx service. It's useful for verifying that Nginx is running correctly after configuration changes or restarts.

```bash
sudo servicectl status nginx
```

--------------------------------

### Search and Read Records from Odoo res.partner Model

Source: https://github.com/openspp/documentation/blob/main/docs/technical_reference/external_api.rst

Demonstrates how to search for and read records from the `res.partner` model, filtering for companies and limiting results to 5. Includes examples in PHP and Java, followed by the expected JSON result structure.

```php
$models->execute_kw($db, $uid, $password, 'res.partner', 'search_read', array(array(array('is_company', '=', true))), array('fields'=>array('name', 'country_id', 'comment'), 'limit'=>5));
```

```java
asList((Object[])models.execute("execute_kw", asList(
    db, uid, password,
    "res.partner", "search_read",
    asList(asList(
        asList("is_company", "=", true))),
    new HashMap() {{
        put("fields", asList("name", "country_id", "comment"));
        put("limit", 5);
    }}
)));
```

```json
[
    {
        "comment": false,
        "country_id": [ 21, "Belgium" ],
        "id": 7,
        "name": "Agrolait"
    },
    {
        "comment": false,
        "country_id": [ 76, "France" ],
        "id": 18,
        "name": "Axelor"
    },
    {
        "comment": false,
        "country_id": [ 233, "United Kingdom" ],
        "id": 12,
        "name": "Bank Wealthy and sons"
    },
    {
        "comment": false,
        "country_id": [ 105, "India" ],
        "id": 14,
        "name": "Best Designers"
    },
    {
        "comment": false,
        "country_id": [ 76, "France" ],
        "id": 17,
        "name": "Camptocamp"
    }
]
```

--------------------------------

### Configure Odoo Queue Job Channels

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This configuration snippet, typically placed in an Odoo configuration file, defines the number of channels for Odoo's asynchronous queue jobs. Setting `channels = root:4` allocates 4 workers to the root queue, which helps OpenSPP remain responsive by processing background tasks efficiently.

```ini
[queue_job]
channels = root:4
```

--------------------------------

### Add Missing HTML Meta Data

Source: https://github.com/openspp/documentation/blob/main/docs/contributing/setup-build.md

Command to automatically add a meta data section to each chapter of the documentation if it is currently missing. This helps improve SEO and how the documentation appears when shared on social media.

```shell
make html_meta
```

--------------------------------

### OpenSPP Administrative Area Import File Schema

Source: https://github.com/openspp/documentation/blob/main/docs/tutorial/user_guides/import_areas.md

Defines the required and optional column headers for the administrative area import file in OpenSPP, including data types, examples, and descriptions for general and parent-level area attributes.

```APIDOC
Import File Column Headers:
  General Columns:
    1. ADM{level}_PCODE:
      Description: Unique code for the administrative area at the current level.
      Example: CN01 for a province code.
      Required: Yes.
    2. ADM{level}_<ISO_CODE>:
      Description: Name of the administrative area in various languages. Replace <ISO_CODE> with the language's ISO code (e.g., EN, FR).
      Example: ADM1_EN for the English name of a first-level administrative area.
      Required: At least one language column must be provided. Multiple language columns are supported.
    3. AREA_SQKM:
      Description: Size of the administrative area in square kilometers.
      Required: No. If provided, must be numerical.
  Parent Area Columns (For levels > 0):
    4. ADM{parent_level}_PCODE:
      Description: Code of the parent administrative area (one level above).
      Example: ADM0_PCODE in ADM1 sheet.
      Required: Yes for levels > 0.
    5. ADM{parent_level}_<ISO_CODE>:
      Description: Name of the parent administrative area in various languages.
      Required: Yes for levels > 0.
```

--------------------------------

### Define Module Dependencies in Odoo Manifest

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/custom_audit.md

This Python snippet shows how to declare module dependencies in an Odoo manifest file. It specifies that the custom module depends on 'spp_audit_log', ensuring that the audit log module is installed before this custom module.

```Python
"depends": [
    "spp_audit_log",
],
```

--------------------------------

### JSON Output for Model Fields Metadata

Source: https://github.com/openspp/documentation/blob/main/docs/technical_reference/external_api.rst

Example JSON structure representing the metadata of various model fields, typically returned by a `fields_get` operation. It includes common fields like `create_uid`, `create_date`, `display_name`, and `id` with their types and user-friendly labels.

```json
{
    "create_uid": {
        "type": "many2one",
        "string": "Created by"
    },
    "create_date": {
        "type": "datetime",
        "string": "Created on"
    },
    "__last_update": {
        "type": "datetime",
        "string": "Last Modified on"
    },
    "write_uid": {
        "type": "many2one",
        "string": "Last Updated by"
    },
    "write_date": {
        "type": "datetime",
        "string": "Last Updated on"
    },
    "display_name": {
        "type": "char",
        "string": "Display Name"
    },
    "id": {
        "type": "integer",
        "string": "Id"
    }
}
```

--------------------------------

### Configure Nginx as a Reverse Proxy for OpenSPP

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This Nginx configuration block sets up a reverse proxy for OpenSPP, handling both standard HTTP traffic and WebSocket communication. It defines upstream servers for Odoo and Odoo chat, configures proxy headers, timeouts, and logging, and redirects requests to the appropriate backend services based on the URL path.

```nginx
proxy_http_version 1.1;
proxy_set_header Host $host;

upstream odoo {
  server 127.0.0.1:17069;
}
upstream odoochat {
  server 127.0.0.1:8072;
}
map $http_upgrade $connection_upgrade {
  default upgrade;
  '' close;
}
server {
listen 8080;
server_name localhost 127.0.0.1;

proxy_read_timeout 720s;
proxy_connect_timeout 720s;
proxy_send_timeout 720s;

# log
access_log /var/log/nginx/odoo.access.log;
error_log /var/log/nginx/odoo.error.log;

# Redirect requests to odoo backend server
location / {
  proxy_set_header X-Forwarded-Host $host;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_redirect off;
  proxy_pass http://odoo;
}

# Redirect websocket requests to odoo gevent port
location /websocket {
  proxy_pass http://odoochat;
  proxy_set_header X-Forwarded-Host $host;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection $connection_upgrade;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
```

--------------------------------

### Read Specific Fields from res.partner Model

Source: https://github.com/openspp/documentation/blob/main/docs/technical_reference/external_api.rst

This example demonstrates how to use `execute_kw` to read specific fields ('name', 'country_id', 'comment') from records in the `res.partner` model. It shows how to pass a dictionary of options, specifically the 'fields' attribute, to control the data returned.

```python
models.execute_kw(db, uid, password, 'res.partner', 'read', [ids], {'fields': ['name', 'country_id', 'comment']})
```

```ruby
models.execute_kw(db, uid, password, 'res.partner', 'read', [ids], {fields: %w(name country_id comment)})
```

```php
$models->execute_kw($db, $uid, $password, 'res.partner', 'read', array($ids), array('fields'=>array('name', 'country_id', 'comment')));
```

```java
asList((Object[])models.execute("execute_kw", asList(
    db, uid, password,
    "res.partner", "read",
    asList(ids),
    new HashMap() {{
        put("fields", asList("name", "country_id", "comment"));
    }}
)));
```

--------------------------------

### Create PostgreSQL User and Database for Odoo

Source: https://github.com/openspp/documentation/blob/main/docs/howto/developer_guides/setting_up_using_pypi.md

This set of commands configures PostgreSQL for Odoo. It creates a new PostgreSQL user named 'odoo' with a password, creates a database also named 'odoo', and grants the 'odoo' user comprehensive privileges on the public schema within that database. Additionally, it modifies the `pg_hba.conf` file to allow local authentication for the 'odoo' user.

```bash
sudo -u postgres createuser -d -R -S -P odoo
sudo -u postgres createdb odoo

sudo -u postgres psql -d odoo -c "GRANT USAGE ON SCHEMA public TO odoo; GRANT CREATE ON SCHEMA public TO odoo; GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO odoo; GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO odoo; GRANT ALL PRIVILEGES ON ALL FUNCTIONS IN SCHEMA public TO odoo;"

sudo su -l postgres -c 'echo "host odoo odoo 127.0.0.1/32 scram-sha-256" >> `psql -c "show hba_file" | sed -n "3p"`'
```