Skip to content

Commit 24cf2f6

Browse files
fabiobaltiericarlescufi
fabiobaltieri
authored and
carlescufi
committed
doc: use substitutions to replace all current harcoded SDK versions
This creates a set of substitution rules to replace all current usages of SDK versions in the documentation, apart from a few that were not meant to be copy-pastable anyway and the version has just been swapped with a <version> placeholder. Since code-block does not parse the content, these have all been replaced with parsed-literal. That one though parses URLs, which cannot be broken, so a series of URL substitutions are provided too. Signed-off-by: Fabio Baltieri <[email protected]>
1 parent 53f0180 commit 24cf2f6

File tree

3 files changed

+67
-54
lines changed

3 files changed

+67
-54
lines changed

‎doc/conf.py‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,10 @@
6666

6767
release = version
6868

69+
# parse SDK version from 'SDK_VERSION' file
70+
with open(ZEPHYR_BASE / "SDK_VERSION") as f:
71+
sdk_version = f.read().strip()
72+
6973
# -- General configuration ------------------------------------------------
7074

7175
extensions = [
@@ -131,8 +135,22 @@
131135
("c:identifier", "va_list"),
132136
]
133137

134-
rst_epilog = """
138+
SDK_URL_BASE="https://github.com/zephyrproject-rtos/sdk-ng/releases/download"
139+
140+
rst_epilog = f"""
135141
.. include:: /substitutions.txt
142+
143+
.. |sdk-version-literal| replace:: ``{sdk_version}``
144+
.. |sdk-version-trim| unicode:: {sdk_version}
145+
:trim:
146+
.. |sdk-version-ltrim| unicode:: {sdk_version}
147+
:ltrim:
148+
.. _Zephyr SDK bundle: https://github.com/zephyrproject-rtos/sdk-ng/releases/tag/v{sdk_version}
149+
.. |sdk-url-linux| replace:: `{SDK_URL_BASE}/v{sdk_version}/zephyr-sdk-{sdk_version}_linux-x86_64.tar.xz`
150+
.. |sdk-url-linux-sha| replace:: `{SDK_URL_BASE}/v{sdk_version}/sha256.sum`
151+
.. |sdk-url-macos| replace:: `{SDK_URL_BASE}/v{sdk_version}/zephyr-sdk-{sdk_version}_macos-x86_64.tar.xz`
152+
.. |sdk-url-macos-sha| replace:: `{SDK_URL_BASE}/v{sdk_version}/sha256.sum`
153+
.. |sdk-url-windows| replace:: `{SDK_URL_BASE}/v{sdk_version}/zephyr-sdk-{sdk_version}_windows-x86_64.7z`
136154
"""
137155

138156
# -- Options for HTML output ----------------------------------------------

‎doc/develop/getting_started/installation_linux.rst‎

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -227,32 +227,31 @@ The Zephyr SDK supports the following target architectures:
227227

228228
Follow these steps to install the Zephyr SDK:
229229

230-
#. Download and verify the `Zephyr SDK bundle
231-
<https://github.com/zephyrproject-rtos/sdk-ng/releases/tag/v0.16.4>`_:
230+
#. Download and verify the `Zephyr SDK bundle`_:
232231

233-
.. code-block:: bash
232+
.. parsed-literal::
234233
235-
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.4/zephyr-sdk-0.16.4_linux-x86_64.tar.xz
236-
wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.4/sha256.sum | shasum --check --ignore-missing
234+
wget |sdk-url-linux|
235+
wget -O - |sdk-url-linux-sha| | shasum --check --ignore-missing
237236
238-
You can change ``0.16.4`` to another version if needed; the `Zephyr SDK
239-
Releases`_ page contains all available SDK releases.
237+
You can change |sdk-version-literal| to another version if needed; the
238+
`Zephyr SDK Releases`_ page contains all available SDK releases.
240239

241240
If your host architecture is 64-bit ARM (for example, Raspberry Pi), replace
242241
``x86_64`` with ``aarch64`` in order to download the 64-bit ARM Linux SDK.
243242

244243
#. Extract the Zephyr SDK bundle archive:
245244

246-
.. code-block:: bash
245+
.. parsed-literal::
247246
248247
cd <sdk download directory>
249-
tar xvf zephyr-sdk-0.16.4_linux-x86_64.tar.xz
248+
tar xvf zephyr-sdk- |sdk-version-trim| _linux-x86_64.tar.xz
250249
251250
#. Run the Zephyr SDK bundle setup script:
252251

253-
.. code-block:: bash
252+
.. parsed-literal::
254253
255-
cd zephyr-sdk-0.16.4
254+
cd zephyr-sdk- |sdk-version-ltrim|
256255
./setup.sh
257256
258257
If this fails, make sure Zephyr's dependencies were installed as described
@@ -271,9 +270,9 @@ If you relocate the SDK directory, you need to re-run the setup script.
271270
* ``/opt``
272271
* ``/usr/local``
273272

274-
The Zephyr SDK bundle archive contains the ``zephyr-sdk-0.16.4`` directory and, when
275-
extracted under ``$HOME``, the resulting installation path will be
276-
``$HOME/zephyr-sdk-0.16.4``.
273+
The Zephyr SDK bundle archive contains the ``zephyr-sdk-<version>``
274+
directory and, when extracted under ``$HOME``, the resulting installation
275+
path will be ``$HOME/zephyr-sdk-<version>``.
277276

278277
If you install the Zephyr SDK outside any of these locations, you must
279278
register the Zephyr SDK in the CMake package registry by running the setup

‎doc/develop/toolchains/zephyr_sdk.rst‎

Lines changed: 35 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ Zephyr SDK installation
7474

7575
.. toolchain_zephyr_sdk_install_start
7676
77-
.. note:: You can change ``0.16.4`` to another version in the instructions below
77+
.. note:: You can change |sdk-version-literal| to another version in the instructions below
7878
if needed; the `Zephyr SDK Releases`_ page contains all available
7979
SDK releases.
8080

@@ -87,23 +87,22 @@ Zephyr SDK installation
8787

8888
.. _ubuntu_zephyr_sdk:
8989

90-
#. Download and verify the `Zephyr SDK bundle
91-
<https://github.com/zephyrproject-rtos/sdk-ng/releases/tag/v0.16.4>`_:
90+
#. Download and verify the `Zephyr SDK bundle`_:
9291

93-
.. code-block:: bash
92+
.. parsed-literal::
9493
9594
cd ~
96-
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.4/zephyr-sdk-0.16.4_linux-x86_64.tar.xz
97-
wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.4/sha256.sum | shasum --check --ignore-missing
95+
wget |sdk-url-linux|
96+
wget -O - |sdk-url-linux-sha| | shasum --check --ignore-missing
9897
9998
If your host architecture is 64-bit ARM (for example, Raspberry Pi), replace ``x86_64``
10099
with ``aarch64`` in order to download the 64-bit ARM Linux SDK.
101100

102101
#. Extract the Zephyr SDK bundle archive:
103102

104-
.. code-block:: bash
103+
.. parsed-literal::
105104
106-
tar xvf zephyr-sdk-0.16.4_linux-x86_64.tar.xz
105+
tar xvf zephyr-sdk- |sdk-version-trim| _linux-x86_64.tar.xz
107106
108107
.. note::
109108
It is recommended to extract the Zephyr SDK bundle at one of the following locations:
@@ -115,15 +114,15 @@ Zephyr SDK installation
115114
* ``/opt``
116115
* ``/usr/local``
117116

118-
The Zephyr SDK bundle archive contains the ``zephyr-sdk-0.16.4`` directory and, when
119-
extracted under ``$HOME``, the resulting installation path will be
120-
``$HOME/zephyr-sdk-0.16.4``.
117+
The Zephyr SDK bundle archive contains the ``zephyr-sdk-<version>``
118+
directory and, when extracted under ``$HOME``, the resulting
119+
installation path will be ``$HOME/zephyr-sdk-<version>``.
121120

122121
#. Run the Zephyr SDK bundle setup script:
123122

124-
.. code-block:: bash
123+
.. parsed-literal::
125124
126-
cd zephyr-sdk-0.16.4
125+
cd zephyr-sdk- |sdk-version-ltrim|
127126
./setup.sh
128127
129128
.. note::
@@ -135,32 +134,31 @@ Zephyr SDK installation
135134
#. Install `udev <https://en.wikipedia.org/wiki/Udev>`_ rules, which
136135
allow you to flash most Zephyr boards as a regular user:
137136

138-
.. code-block:: bash
137+
.. parsed-literal::
139138
140-
sudo cp ~/zephyr-sdk-0.16.4/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
139+
sudo cp ~/zephyr-sdk- |sdk-version-trim| /sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
141140
sudo udevadm control --reload
142141
143142
.. group-tab:: macOS
144143

145144
.. _macos_zephyr_sdk:
146145

147-
#. Download and verify the `Zephyr SDK bundle
148-
<https://github.com/zephyrproject-rtos/sdk-ng/releases/tag/v0.16.4>`_:
146+
#. Download and verify the `Zephyr SDK bundle`_:
149147

150-
.. code-block:: bash
148+
.. parsed-literal::
151149
152150
cd ~
153-
curl -L -O https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.4/zephyr-sdk-0.16.4_macos-x86_64.tar.xz
154-
curl -L https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.4/sha256.sum | shasum --check --ignore-missing
151+
curl -L -O |sdk-url-macos|
152+
curl -L |sdk-url-macos-sha| | shasum --check --ignore-missing
155153
156154
If your host architecture is 64-bit ARM (Apple Silicon, also known as M1), replace
157155
``x86_64`` with ``aarch64`` in order to download the 64-bit ARM macOS SDK.
158156

159157
#. Extract the Zephyr SDK bundle archive:
160158

161-
.. code-block:: bash
159+
.. parsed-literal::
162160
163-
tar xvf zephyr-sdk-0.16.4_macos-x86_64.tar.xz
161+
tar xvf zephyr-sdk- |sdk-version-trim| _macos-x86_64.tar.xz
164162
165163
.. note::
166164
It is recommended to extract the Zephyr SDK bundle at one of the following locations:
@@ -172,15 +170,15 @@ Zephyr SDK installation
172170
* ``/opt``
173171
* ``/usr/local``
174172

175-
The Zephyr SDK bundle archive contains the ``zephyr-sdk-0.16.4`` directory and, when
176-
extracted under ``$HOME``, the resulting installation path will be
177-
``$HOME/zephyr-sdk-0.16.4``.
173+
The Zephyr SDK bundle archive contains the ``zephyr-sdk-<version>``
174+
directory and, when extracted under ``$HOME``, the resulting
175+
installation path will be ``$HOME/zephyr-sdk-<version>``.
178176

179177
#. Run the Zephyr SDK bundle setup script:
180178

181-
.. code-block:: bash
179+
.. parsed-literal::
182180
183-
cd zephyr-sdk-0.16.4
181+
cd zephyr-sdk- |sdk-version-ltrim|
184182
./setup.sh
185183
186184
.. note::
@@ -195,35 +193,34 @@ Zephyr SDK installation
195193

196194
#. Open a ``cmd.exe`` terminal window **as a regular user**
197195

198-
#. Download the `Zephyr SDK bundle
199-
<https://github.com/zephyrproject-rtos/sdk-ng/releases/tag/v0.16.4>`_:
196+
#. Download the `Zephyr SDK bundle`_:
200197

201-
.. code-block:: bat
198+
.. parsed-literal::
202199
203200
cd %HOMEPATH%
204-
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.4/zephyr-sdk-0.16.4_windows-x86_64.7z
201+
wget |sdk-url-windows|
205202
206203
#. Extract the Zephyr SDK bundle archive:
207204

208-
.. code-block:: bat
205+
.. parsed-literal::
209206
210-
7z x zephyr-sdk-0.16.4_windows-x86_64.7z
207+
7z x zephyr-sdk- |sdk-version-trim| _windows-x86_64.7z
211208
212209
.. note::
213210
It is recommended to extract the Zephyr SDK bundle at one of the following locations:
214211

215212
* ``%HOMEPATH%``
216213
* ``%PROGRAMFILES%``
217214

218-
The Zephyr SDK bundle archive contains the ``zephyr-sdk-0.16.4`` directory and, when
219-
extracted under ``%HOMEPATH%``, the resulting installation path will be
220-
``%HOMEPATH%\zephyr-sdk-0.16.4``.
215+
The Zephyr SDK bundle archive contains the ``zephyr-sdk-<version>``
216+
directory and, when extracted under ``%HOMEPATH%``, the resulting
217+
installation path will be ``%HOMEPATH%\zephyr-sdk-<version>``.
221218

222219
#. Run the Zephyr SDK bundle setup script:
223220

224-
.. code-block:: bat
221+
.. parsed-literal::
225222
226-
cd zephyr-sdk-0.16.4
223+
cd zephyr-sdk- |sdk-version-ltrim|
227224
setup.cmd
228225
229226
.. note::
@@ -232,7 +229,6 @@ Zephyr SDK installation
232229
You must rerun the setup script if you relocate the Zephyr SDK bundle directory after
233230
the initial setup.
234231

235-
.. _Zephyr SDK bundle: https://github.com/zephyrproject-rtos/sdk-ng/releases/tag/v0.16.4
236232
.. _Zephyr SDK Releases: https://github.com/zephyrproject-rtos/sdk-ng/tags
237233
.. _Zephyr SDK Version Compatibility Matrix: https://github.com/zephyrproject-rtos/sdk-ng/wiki/Zephyr-SDK-Version-Compatibility-Matrix
238234

0 commit comments

Comments
 (0)