Python/libs/ConfigMix: docs/conf.py comparison

comparison docs/conf.py @ 781:236a1d00b8a6

Some documentation tweaks: sync with other projects

author	Franz Glasner <fzglas.hg@dom66.de>
date	Sat, 16 May 2026 14:59:46 +0200
parents	48deafc1fd2f
children	8151ac02f71d

comparison

equal deleted inserted replaced

-:47ae57d92ed3
+:236a1d00b8a6
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import datetime
 import os
 import sys
 sys.path.insert(0, os.path.dirname(os.path.abspath('.')))
 import configmix
 from configmix.compat import u
 project = 'ConfigMix'
 copyright = u('2015–2023, Franz Glasner. All rights reserved')
 author = 'Franz Glasner'
-# The short X.Y version
+current_date = datetime.date.today().isoformat()
-version = '.'.join(configmix.__version__.split('.')[:2])
 # The full version, including alpha/beta/rc tags
 release = configmix.__version__
+# The short X.Y version
+version = '.'.join(release.split('.')[:2])
+#
+# Optimistically assume that all keywords are expanded properly everywhere:
+# do not define special VCSxxx keyword below.
+#
+define_rest_keywords = False
 release_date = today = configmix.__date__
+if (not release_date
-current_date = datetime.date.today().isoformat()
+or (release_date.startswith("|") and release_date.endswith("|"))):
+# Above assumption is not true: "hg kwarchive" nay not have been called
+release_date = today = "dev-%s" % (current_date,)
+define_rest_keywords = True
+release_rev = configmix.__revision__
+if (not release_rev
+or (release_rev.startswith("|") and release_rev.endswith("|"))):
+#
+# Above assumption is not true: "hg kwarchive" may not have been called.
+# Try to determine from VCS.
+#
+import subprocess
+try:
+release_rev = subprocess.check_output(
+["hg", "id", "-i"], stderr=subprocess.STDOUT)
+except Exception:
+release_rev = "<UNKNOWN>"
+else:
+if sys.version_info[0] >= 3:
+release_rev = release_rev.decode("ascii")
+release_rev = "dev-%s" % (release_rev.strip(),)
+define_rest_keywords = True
+else:
+#
+# Assume that all keywords are expanded properly everywhere:
+# do not define special VCSxxx keyword below.
+#
+define_rest_keywords = False
 # -- General configuration ---------------------------------------------------
 # If your documentation needs a minimal Sphinx version, state it here.
 #
 highlight_language = "default"
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
+rst_prolog = """
+.. |release_date| replace:: %s
+.. |release_rev| replace:: %s
+""" % (release_date, release_rev)
+if define_rest_keywords:
+rst_prolog += """\
+.. |VCSJustDate| replace:: %s
+.. |VCSRevision| replace:: %s
+.. |VCSHGRevision| replace:: %s
+""" % (release_date, release_rev, release_rev)
 # -- Options for HTML output -------------------------------------------------
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
 #html_theme = 'alabaster'
 html_theme = 'haiku'
 # for the Haiku title
 html_short_title = u("%s %s") % (project, release)
-html_last_updated_fmt = "%s (rev %s)" % (current_date, configmix.__revision__)
+html_last_updated_fmt = "%s (rev %s)" % (current_date, release_rev)
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
 'pointsize': '11pt',
 'babel': r'\usepackage{babel}',
 'preamble': r'\usepackage[stdtitle=false]{my-doc-style}',
 'maketitle': r'\builddate{%s}\vcsrevision{%s}\sphinxmaketitle' \
-% (current_date, configmix.__revision__),
+% (current_date, release_rev),
 'fontpkg': r'\usepackage[fonts=charter]{my-doc-fonts}',
 # Latex figure (float) alignment
 #
 # 'figure_align': 'htbp',
 'fncychap': r'\usepackage[Sonny]{fncychap}',
 }
 latex_additional_files = [
 "_latex/my-doc-fonts.sty",
 "_latex/my-doc-style.sty",
 ]
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 def setup(app):
 #
 # Custom release_date variable with a custom substitution |release_date|
+# and |release_rev|'.
 #
 app.add_config_value('release_date', '', 'env')
+app.add_config_value('release_rev', '', 'env')
 import sphinx.transforms
 class IAMCustomSubstitutions(sphinx.transforms.SphinxTransform):
 default_priority = sphinx.transforms.DefaultSubstitutions.default_priority
 def apply(self):
 from docutils import nodes
 for ref in self.document.traverse(nodes.substitution_reference):
 refname = ref['refname']
-if refname == 'release_date':
+if refname in ('release_date' 'release_rev'):
 stext = self.config[refname]
 ref.replace_self(nodes.Text(stext, stext))
 app.add_transform(IAMCustomSubstitutions)

Mercurial > hgrepos > Python > libs > ConfigMix

comparison docs/conf.py @ 781:236a1d00b8a6