From: Chris Johns <chr...@rtems.org>
- Support using a version number for RTEMS documentation
Updates #4695
---
README.txt | 31 +++++++++++++++++++++
common/conf.py | 12 +++-----
common/rtemsdomain.py | 64 +++++++++++++++++++++++++++++++------------
common/version.py | 5 +++-
4 files changed, 85 insertions(+), 27 deletions(-)
diff --git a/README.txt b/README.txt
index 828c9e7..07bae0d 100644
--- a/README.txt
+++ b/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`.
diff --git a/common/conf.py b/common/conf.py
index a652e2a..565e06d 100644
--- a/common/conf.py
+++ b/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()
-
-major = rtems_version.major()
-minor = rtems_version.minor()
-revision = rtems_version.revision()
+#release = rtems_version.string()
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/common/rtemsdomain.py b/common/rtemsdomain.py
index 9b092a3..630f1e3 100644
--- a/common/rtemsdomain.py
+++ b/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";),
- "devel": ("Developer Site",
"https://devel.rtems.org";),
- "www": ("RTEMS Home",
"https://www.rtems.org/";),
- "buildbot": ("Buildbot Instance",
"https://buildbot.rtems.org/";),
- "builder": ("Builder Site",
"https://builder.rtems.org/";),
- "docs": ("Documentation Site",
"https://docs.rtems.org/";),
- "lists": ("Mailing Lists",
"https://lists.rtems.org/";),
- "git": ("Git Repositories",
"https://git.rtems.org/";),
- "ftp": ("FTP File Server",
"https://ftp.rtems.org/";),
- "review": ("Gerrit Code Review",
"https://review.rtems.org/";),
- "bugs": ("Bugs Database",
"https://devel.rtems.org/wiki/Bugs/";),
- "gsoc": ("Google Summer of Code",
"https://devel.rtems.org/wiki/GSoC/";),
- "socis": ("ESA SOCIS",
"https://devel.rtems.org/wiki/SOCIS/";)
+ "trac": ("Trac",
"https://devel.rtems.org";),
+ "devel": ("Developer Site",
"https://devel.rtems.org";),
+ "www": ("RTEMS Home",
"https://www.rtems.org/";),
+ "buildbot": ("Buildbot Instance",
"https://buildbot.rtems.org/";),
+ "builder": ("Builder Site",
"https://builder.rtems.org/";),
+ "docs": ("Documentation Site",
"https://docs.rtems.org/";),
+ "lists": ("Mailing Lists",
"https://lists.rtems.org/";),
+ "git": ("Git Repositories",
"https://git.rtems.org/";),
+ "ftp": ("FTP File Server",
"https://ftp.rtems.org/";),
+ "review": ("Gerrit Code Review",
"https://review.rtems.org/";),
+ "bugs": ("Bugs Database",
"https://devel.rtems.org/wiki/Bugs/";),
+ "gsoc": ("Google Summer of Code",
"https://devel.rtems.org/wiki/GSoC/";),
+ "socis": ("ESA SOCIS",
"https://devel.rtems.org/wiki/SOCIS/";)
}
role_list = {
- "announce": ("Announce Mailing List",
"https://lists.rtems.org/mailman/listinfo/announce/";),
- "bugs": ("Bugs Mailing List",
"https://lists.rtems.org/mailman/listinfo/bugs/";),
- "devel": ("Developers Mailing List",
"https://lists.rtems.org/mailman/listinfo/devel/";),
- "build": ("Build Logs",
"https://lists.rtems.org/mailman/listinfo/build";),
- "users": ("Users Mailing List",
"https://lists.rtems.org/mailman/listinfo/users/";),
+ "announce": ("Announce Mailing List",
"https://lists.rtems.org/mailman/listinfo/announce/";),
+ "bugs": ("Bugs Mailing List",
"https://lists.rtems.org/mailman/listinfo/bugs/";),
+ "devel": ("Developers Mailing List",
"https://lists.rtems.org/mailman/listinfo/devel/";),
+ "build": ("Build Logs",
"https://lists.rtems.org/mailman/listinfo/build";),
+ "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}
diff --git a/common/version.py b/common/version.py
index 281c880..bfe0e1b 100644
--- a/common/version.py
+++ b/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
--
2.24.1
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
