building: Add support for an RTEMS version number

- Support using a version number for RTEMS documentation

Updates #4695

README.txt

@@ -504,6 +504,9 @@ existing documentation for an example and if unsure ask.
    identifed by the standard shell prompt characters where '$' is a
    user prompt and '#' is a 'root' prompt.
 
+   Do not embed the version or version major number in the literal
+   commands or examples. Use the replacements listed in 10.
+
 6. Use the directives for 'note', 'warning', and 'topic'. Do not add 'TIP',
    'Important' or 'Warning' to the text. Let the mark-up language handle
    this. The supported directives are:
@@ -582,3 +585,31 @@ existing documentation for an example and if unsure ask.
      bugs         : https://devel.rtems.org/wiki/Bugs/
      gsoc         : https://devel.rtems.org/wiki/GSoC/
      socis        : https://devel.rtems.org/wiki/SOCIS/
+
+10. Use the following to embed the version number in any part of the
+    documentation source:
+
+     1. @rtems-version@
+
+        The complete version string of the documentation.
+
+     2. @rtems-ver-major@
+
+        The version major number.
+
+     2. @rtems-ver-minor@
+
+        The version minor number.
+
+     2. @rtems-ver-revision@
+
+        The version revision number.
+
+    The replacement happens during the source read phase of the build
+    and is not context specific. The subsituation will happen in code
+    blocks and other normally quoated area.
+
+    It is a requirement these be used then embedded commands or
+    related text in the documentation to let the documentatoin track
+    the release. For example `microblaze-rtems6-gdb` should be written
+    as `microblaze-rtems@rtems-ver-major@-gdb`.

common/conf.py

@@ -1,4 +1,4 @@
-import version as rtems_version
+import datetime
 
 extensions = [
 	"sphinx.ext.autodoc",
@@ -30,21 +30,17 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'RTEMS Documentation Project'
-copyright = u'1988, 2020 RTEMS Project and contributors'
+copyright = u'1988, ' + str(datetime.datetime.now().year) + ' RTEMS Project and contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = rtems_version.version()
+#version = rtems_version.version()
 
 # The full version, including alpha/beta/rc tags.
-release = rtems_version.string()
+#release = rtems_version.string()
-
-major = rtems_version.major()
-minor = rtems_version.minor()
-revision = rtems_version.revision()
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

common/rtemsdomain.py

@@ -8,6 +8,8 @@ from sphinx.domains import Domain, ObjType, Index
 from sphinx.util.nodes import make_refnode
 from sphinx.util.docfields import Field, TypedField
 
+import version as rtems_version
+
 """
 :r:bsp:`sparc/sis`
 
@@ -30,28 +32,28 @@ role_name = {
 }
 
 role_url = {
-	"trac": 			("Trac",				"https://devel.rtems.org"),
+	"trac": 	("Trac",			"https://devel.rtems.org"),
-	"devel": 			("Developer Site",		"https://devel.rtems.org"),
+	"devel": 	("Developer Site",		"https://devel.rtems.org"),
-	"www":				("RTEMS Home",			"https://www.rtems.org/"),
+	"www":		("RTEMS Home",			"https://www.rtems.org/"),
-	"buildbot":			("Buildbot Instance",	"https://buildbot.rtems.org/"),
+	"buildbot":	("Buildbot Instance",		"https://buildbot.rtems.org/"),
-	"builder":			("Builder Site",		"https://builder.rtems.org/"),
+	"builder":	("Builder Site",		"https://builder.rtems.org/"),
-	"docs":				("Documentation Site",	"https://docs.rtems.org/"),
+	"docs":		("Documentation Site",		"https://docs.rtems.org/"),
-	"lists":			("Mailing Lists",		"https://lists.rtems.org/"),
+	"lists":	("Mailing Lists",		"https://lists.rtems.org/"),
-	"git":				("Git Repositories",	"https://git.rtems.org/"),
+	"git":		("Git Repositories",		"https://git.rtems.org/"),
-	"ftp":				("FTP File Server",	"https://ftp.rtems.org/"),
+	"ftp":		("FTP File Server",		"https://ftp.rtems.org/"),
-	"review":			("Gerrit Code Review",	"https://review.rtems.org/"),
+	"review":	("Gerrit Code Review",		"https://review.rtems.org/"),
-	"bugs":				("Bugs Database",		"https://devel.rtems.org/wiki/Bugs/"),
+	"bugs":		("Bugs Database",		"https://devel.rtems.org/wiki/Bugs/"),
-	"gsoc":				("Google Summer of Code", "https://devel.rtems.org/wiki/GSoC/"),
+	"gsoc":		("Google Summer of Code", 	"https://devel.rtems.org/wiki/GSoC/"),
-	"socis":			("ESA SOCIS",			"https://devel.rtems.org/wiki/SOCIS/")
+	"socis":	("ESA SOCIS",			"https://devel.rtems.org/wiki/SOCIS/")
 }
 
 
 role_list = {
-	"announce":	("Announce Mailing List",			"https://lists.rtems.org/mailman/listinfo/announce/"),
+	"announce":	("Announce Mailing List",		"https://lists.rtems.org/mailman/listinfo/announce/"),
-	"bugs":		("Bugs Mailing List",				"https://lists.rtems.org/mailman/listinfo/bugs/"),
+	"bugs":		("Bugs Mailing List",			"https://lists.rtems.org/mailman/listinfo/bugs/"),
-	"devel":	("Developers Mailing List",			"https://lists.rtems.org/mailman/listinfo/devel/"),
+	"devel":	("Developers Mailing List",		"https://lists.rtems.org/mailman/listinfo/devel/"),
-	"build":	("Build Logs",					"https://lists.rtems.org/mailman/listinfo/build"),
+	"build":	("Build Logs",				"https://lists.rtems.org/mailman/listinfo/build"),
-	"users":	("Users Mailing List",				"https://lists.rtems.org/mailman/listinfo/users/"),
+	"users":	("Users Mailing List",			"https://lists.rtems.org/mailman/listinfo/users/"),
 	"vc":		("Version Control Mailing List",	"https://lists.rtems.org/mailman/listinfo/vc/"),
 }
 
@@ -119,7 +121,33 @@ class RTEMSDomain(Domain):
 		pass # XXX is this needed?
 
 
+def rtems_replace(app, docname, source):
+	dump = False
+	line = source[0]
+	for key in app.config.replacements:
+		line = line.replace(key, app.config.replacements[key])
+	source[0] = line
+
+replacements = {
+}
 
 def setup(app):
+	app.add_config_value('rtems_major', str(app.config.overrides['rtems_major']), True)
+	app.add_config_value('rtems_minor', str(app.config.overrides['rtems_minor']), True)
+	app.add_config_value('rtems_revision', str(app.config.overrides['rtems_revision']), True)
+	major = str(app.config.overrides['rtems_major'])
+	minor = str(app.config.overrides['rtems_minor'])
+	revision = str(app.config.overrides['rtems_revision'])
+	if revision.isdigit():
+		majminrev = major + '.' + minor + '.' + revision
+	else:
+		majminrev = major + '.' + revision
+	replacements["@rtems-version@"] = str(app.config.overrides['version'])
+	replacements["@rtems-ver-major@"] = major
+	replacements["@rtems-ver-minor@"] = minor
+	replacements["@rtems-ver-revision@"] = revision
+	replacements["@rtems-ver-majminrev@"] = majminrev
+	app.add_config_value('replacements', replacements, True)
+	app.connect('source-read', rtems_replace)
 	app.add_domain(RTEMSDomain)
 	return {'version': "1.0", 'parallel_read_safe': True}

common/version.py

@@ -111,6 +111,9 @@ def _pretty_day(ctx, date):
 
 def get(ctx, rtems_major_version):
     global _version
+    global _major
+    global _minor
+    global _revision
     global _date
     global _released
     version = _version
@@ -184,7 +187,7 @@ def minor():
     return _minor
 
 def revision():
-    return revision
+    return _revision
 
 def date():
     return _date