From e4ac15e6035b9c18a4cfd1a81598a74e8b820d22 Mon Sep 17 00:00:00 2001 From: "Antoine Vandevenne (anv)" Date: Fri, 31 Oct 2025 15:54:00 +0000 Subject: [PATCH] [IMP] README: restructure content and document additional commands X-original-commit: 29614b8cec04231013eccfc9bca6f2e1619dfc4a --- Makefile | 3 ++- README.md | 77 ++++++++++++++++++++++++++++++++++++++----------------- 2 files changed, 55 insertions(+), 25 deletions(-) diff --git a/Makefile b/Makefile index fb1c9d116d..2fdfbe4fc2 100644 --- a/Makefile +++ b/Makefile @@ -91,7 +91,8 @@ static: $(HTML_BUILD_DIR)/_static/style.css test: @python tests/main.py $(SOURCE_DIR)/administration $(SOURCE_DIR)/applications $(SOURCE_DIR)/contributing $(SOURCE_DIR)/developer redirects -# Similar as `test`, but called only manually by content reviewers to trigger extra checks. +# Similar to `test`, but called only manually by content reviewers to specify a path and a max line +# length. review: @read -p "Enter relative content path: " path; read -p "Enter max line length (default: 100): " line_length; \ if [ -z "$$path" ]; then echo "Error: Path cannot be empty"; exit 1; fi; \ diff --git a/README.md b/README.md index 956011c884..10954bee25 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,67 @@ # Odoo documentation -## Build the documentation locally +## Build the documentation ### Requirements -- Git -- Python 3.6, 3.7, or 3.8 -- Python dependencies listed in the file `requirements.txt`. +- [Git](https://git-scm.com/install) +- [Python 3.10 to 3.14](https://www.python.org/downloads/). - Make -- A local copy of the [odoo/odoo repository](https://github.com/odoo/odoo) (optional) -- A local copy of the [odoo/upgrade-util repository](https://github.com/odoo/upgrade-util) (optional) +- Python dependencies from `requirements.txt` (see instructions below) +- A local copy of the [odoo/odoo](https://github.com/odoo/odoo) repository (optional) +- A local copy of the [odoo/upgrade-util](https://github.com/odoo/upgrade-util) repository + (optional) -### Instructions +### Quick start -1. In a terminal, navigate to the root directory of the documentation and build it `make`. - Additional commands are available with `make help`. -2. Open the file `documentation/_build/html/index.html` in your web browser. -3. See [this guide](https://www.odoo.com/documentation/latest/contributing/documentation.html) - for more detailed instructions. +1. Create and activate a virtual environment. + - On Linux and macOS: `python3 -m venv .venv && source .venv/bin/activate` + - On Windows (PowerShell): `py3 -m venv .venv; .\.venv\Scripts\Activate.ps1` +2. Install the Python dependencies: `pip install -r requirements.txt` +3. Build the documentation: `make html` (see more commands with `make help`) +4. Open `documentation/_build/html/index.html` in your web browser. -Optional: place your local copy of the `odoo/odoo` and `odoo/upgrade-util` repositories in -the parent directory or in the root directory of the documentation to build the latter -with the documented Python docstrings. +### Additional build options -## Contribute to the documentation +- `make fast` to build the documentation with a shallow menu (faster). +- `make clean` to delete the build files. +- `make test` to run the guidelines tests. +- `make html CURRENT_LANG=fr` to build the documentation only in French. +- `make html CURRENT_LANG=fr LANGUAGES=en,fr,de` to build the documentation in French and enable the + language switcher, with the specified LANGUAGES as available languages. This command must be + invoked for each CURRENT_LANG you want to build. +- `make html VERSIONS=17.0,18.0,saas-18.4,19.0,master` to build the documentation in the **current + version** and enable the version switcher, with the specified VERSIONS as available versions. This + command must be invoked for each of the VERSIONS you want to build. -For contributions to the content of the documentation, please refer to the -[Introduction Guide](https://www.odoo.com/documentation/latest/contributing/documentation.html). +The list of available languages can be found in `conf.py`, in the `languages_names` variable. + +When building the documentation for a specific language or version, the build files are created in +`documentation/_build/html//`, `documentation/_build/html//` or +`documentation/_build/html///`. + +### Using local Odoo sources + +If you have local checkouts of `odoo/odoo` and/or `odoo/upgrade-util`, place them either: +- as siblings of this repository (in the parent directory), or +- inside the `documentation` directory. -To **report a content issue**, **request new content** or **ask a question**, use the -[repository's issue tracker](https://github.com/odoo/documentation/issues). +When present in one of these locations, the build will include Python docstrings from those +repositories if their version matches the documentation's version. -## Learn More +### Troubleshooting + +- Verify your Python version: `python3 --version` (must be 3.10–3.14) +- Ensure your virtual environment is active and dependencies are installed. +- If you have made changes to the file structure, try `make clean` before building. +- If the language or version switchers redirect to a missing file, check that you have built the + documentation for all available languages and versions. +- The "Developer" documentation is only available in English. + +## Contribute to the documentation + +For contributions to the content of the documentation, see the +[Introduction Guide](https://www.odoo.com/documentation/latest/contributing/documentation.html). -To learn more about Odoo, in addition to the documentation, have a look at -[the official eLearning](https://odoo.com/slides) and -[Scale-up, The Business Game](https://www.odoo.com/page/scale-up-business-game). +To report a content issue, request new content, or ask a question, use the +[issue tracker](https://github.com/odoo/documentation/issues).