docs: Add github.ref_name cheatsheet + clarification

Signed-off-by: Jorge Marques <[email protected]>
analogdevicesinc · Feb 9, 2025 · 586896f · 586896f
1 parent c4f7484
commit 586896f
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 2 deletions.
diff --git a/docs/ci.rst b/docs/ci.rst
@@ -277,6 +277,9 @@ For example:
 Notice how the "name" and "label" for path ``prs/staging/new-feature``
 was used to provide a concise but clearer name to this entry.
 
+The doc version set, either via ``conf.py`` or ``ADOC_DOC_VERSION`` (:ref:`more info <version>`),
+should match a value on the ``name`` column, and not the ``path`` column.
+
 Further notes
 +++++++++++++
 

diff --git a/docs/cli.rst b/docs/cli.rst
@@ -84,7 +84,7 @@ Why was Author Mode renamed to Serve?
 +++++++++++++++++++++++++++++++++++++
 
 Solely to match other tools like ``mkdocs serve``, ``webpack serve``,
-``npm run start``, ``hugo server``,
+``npm run start``, ``hugo server``.
 
 .. _custom-doc:
 

diff --git a/docs/docs_guidelines/index.rst b/docs/docs_guidelines/index.rst
@@ -133,7 +133,8 @@ The ``version`` value on ``conf.py`` has lower precedence, and
 will be overwritten if ``ADOC_DOC_VERSION`` is set.
 
 The CI, in general, should set ``ADOC_DOC_VERSION`` as the current checkout branch
-in the pipeline (e.g. ``main``, ``v1.0.0``).
+in the pipeline (e.g. ``main``, ``v1.0.0``), for GiHub Actions, that can be
+``${{ github.ref_name}}`` [#f1]_.
 
 .. tip::
 
@@ -143,6 +144,12 @@ in the pipeline (e.g. ``main``, ``v1.0.0``).
 If both environment variable and ``version`` on ``conf.py`` are unset, it defaults
 to an empty string.
 
+.. [#f1] Quick cheatsheet for ``gihtub.ref_name`` values on event:
+
+         * push branch: ``main``, ``dev``, ...
+         * push tag: ``v2.2.2``, ``new-feature``, ...
+         * pull_request: ``1234/merge``, ``23/merge``, ...
+
 Exporting to PDF
 --------------------------------------------------------------------------------