arm-trusted-firmware/.readthedocs.yaml

# Copyright (c) 2023, Arm Limited. All rights reserved
#
# SPDX-License-Identifier: BSD-3-Clause
#
# Configuration file for the readthedocs deploy
# Available at https://trustedfirmware-a.readthedocs.io/en/latest/


# readthedocs config version
version: 2

build:
  os: ubuntu-22.04 # Ubuntu Jammy LTS
  tools:
    python: "3.10"
  apt_packages:
    - plantuml
    - librsvg2-bin
  jobs:
    post_create_environment:
      - pip install poetry=="1.3.2"
      - poetry config virtualenvs.create false
    post_install:
      - poetry install --with doc

sphinx:
  configuration: docs/conf.py

# Auxiliary formats to export to (in addition to the default HTML output).
formats:
  - pdf
fix(docs): add readthedocs configuration file Readthedocs uses weird defaults and the web interface gives limited configuration options. Add the config file to allow them to be changed. Bump build os image to Ubuntu 22.04 to be in line with the CI. Signed-off-by: Boyan Karatotev <boyan.karatotev@arm.com> Change-Id: I1a620b15ab3924244f305056096024fe117c63dd 2 years ago			`# Copyright (c) 2023, Arm Limited. All rights reserved`
			`#`
			`# SPDX-License-Identifier: BSD-3-Clause`
			`#`
			`# Configuration file for the readthedocs deploy`
			`# Available at https://trustedfirmware-a.readthedocs.io/en/latest/`


			`# readthedocs config version`
			`version: 2`

			`build:`
			`os: ubuntu-22.04 # Ubuntu Jammy LTS`
fix(docs): add a build.tools.python entry Specifying build.tools is mandatory. We use python, so use the latest one available. For ubuntu 22.04 that should be 3.10 or thereabouts. Signed-off-by: Boyan Karatotev <boyan.karatotev@arm.com> Change-Id: Ifd184b9f3b2d8e91182ccb73c47b148e4aeaff05 2 years ago			`tools:`
fix(docs): python version must be string Signed-off-by: Boyan Karatotev <boyan.karatotev@arm.com> Change-Id: If5886f8adb391edf3771112cd8e20957a454eae0 2 years ago			`python: "3.10"`
fix(docs): add plantuml as a dependency This wasn't listed on the web interface configuration. Perhaps it came preloaded. Anyway, it's needed for diagrams. Add it back. Signed-off-by: Boyan Karatotev <boyan.karatotev@arm.com> Change-Id: I20c1eb0e8d5abaa3533169dd9704cbd3b0eb06a5 2 years ago			`apt_packages:`
			`- plantuml`
fix: use rsvg-convert as the conversion backend The auxiliary pdf build requires SVG files to be converted to pdf files. Use libRSVG as a light weight alternative to inkscape, and ensure it's installed in the build environment. Change-Id: I1fdb05fb2701fc28a04e210d5928f4387ca08613 Signed-off-by: Harrison Mutai <harrison.mutai@arm.com> 1 year ago			`- librsvg2-bin`
feat: add support for poetry New python dependencies are introduced by the memory mapping script. Rather than add another `requirements.txt` utilise poetry. This is a proper dependency management framework for Python. The two main upsides of using poetry instead of the traditional requirements.txt are maintainability and reproducibility. Poetry provides a proper lock file for pinning dependencies, similar to npm for JavaScript. This allows for separate environments (i.e. docs, tools) to be created efficiently, and in a reproducible manner, wherever the project is deployed. Having dependencies pinned in this manner is a boon as a security focused project. An additional upside is that we will receive security updates for dependencies via GitHub's Dependabot. Change-Id: I5a3c2003769b878a464c8feac0f789e5ecf8d56c Signed-off-by: Harrison Mutai <harrison.mutai@arm.com> 2 years ago			`jobs:`
			`post_create_environment:`
fix: pin poetry to version used in CI Pin poetry to version 1.3.2, which is currently used in CI, to ensure that all builds are consistent. Also, fix typo in `doc` group name. Change-Id: Id0c1aa88ac7ffcc241a51c693570e87abacf7ebc Signed-off-by: Harrison Mutai <harrison.mutai@arm.com> 1 year ago			`- pip install poetry=="1.3.2"`
feat: add support for poetry New python dependencies are introduced by the memory mapping script. Rather than add another `requirements.txt` utilise poetry. This is a proper dependency management framework for Python. The two main upsides of using poetry instead of the traditional requirements.txt are maintainability and reproducibility. Poetry provides a proper lock file for pinning dependencies, similar to npm for JavaScript. This allows for separate environments (i.e. docs, tools) to be created efficiently, and in a reproducible manner, wherever the project is deployed. Having dependencies pinned in this manner is a boon as a security focused project. An additional upside is that we will receive security updates for dependencies via GitHub's Dependabot. Change-Id: I5a3c2003769b878a464c8feac0f789e5ecf8d56c Signed-off-by: Harrison Mutai <harrison.mutai@arm.com> 2 years ago			`- poetry config virtualenvs.create false`
			`post_install:`
fix: pin poetry to version used in CI Pin poetry to version 1.3.2, which is currently used in CI, to ensure that all builds are consistent. Also, fix typo in `doc` group name. Change-Id: Id0c1aa88ac7ffcc241a51c693570e87abacf7ebc Signed-off-by: Harrison Mutai <harrison.mutai@arm.com> 1 year ago			`- poetry install --with doc`
fix(docs): add readthedocs configuration file Readthedocs uses weird defaults and the web interface gives limited configuration options. Add the config file to allow them to be changed. Bump build os image to Ubuntu 22.04 to be in line with the CI. Signed-off-by: Boyan Karatotev <boyan.karatotev@arm.com> Change-Id: I1a620b15ab3924244f305056096024fe117c63dd 2 years ago
			`sphinx:`
			`configuration: docs/conf.py`
Revert "docs: disable PDF output for documentation generation" This reverts commit 279e28ed3526bfcfb8d8bc736e4f5aafd3d73ba3. Reason for revert: Re-enable the pdf generation since the necessary fix to generate pdf has already been merged. Change-Id: Ia68e8caea94b5d89fcf182251a13473b32b4bfad 1 year ago
			`# Auxiliary formats to export to (in addition to the default HTML output).`
			`formats:`
			`- pdf`