From 0469dec71ee0110409067d7cbd56d99a071820a2 Mon Sep 17 00:00:00 2001
From: Martine Lenders <m.lenders@fu-berlin.de>
Date: Thu, 11 May 2017 14:37:37 +0200
Subject: [PATCH] doc: add release notes to doxygen documentation
Provides a script to generate a doxygen page from the
`release-notes.txt` and includes it to the doxygen build.
---
doc/doxygen/.gitignore | 1 +
doc/doxygen/Makefile | 11 ++++--
doc/doxygen/generate-changelog.py | 66 +++++++++++++++++++++++++++++++
doc/doxygen/riot.doxyfile | 3 +-
doc/doxygen/src/changelog.md.tmp | 6 +++
5 files changed, 82 insertions(+), 5 deletions(-)
create mode 100755 doc/doxygen/generate-changelog.py
create mode 100644 doc/doxygen/src/changelog.md.tmp
diff --git a/doc/doxygen/.gitignore b/doc/doxygen/.gitignore
index 6276aff47c..53e838267f 100644
--- a/doc/doxygen/.gitignore
+++ b/doc/doxygen/.gitignore
@@ -1 +1,2 @@
src/css/variables.less
+src/changelog.md
diff --git a/doc/doxygen/Makefile b/doc/doxygen/Makefile
index 544278314c..840bbf9c8e 100644
--- a/doc/doxygen/Makefile
+++ b/doc/doxygen/Makefile
@@ -10,11 +10,11 @@ doc: html
# by marking html as phony we force make to re-run Doxygen even if the directory exists.
.PHONY: html
-html: src/css/riot.css
+html: src/css/riot.css src/changelog.md
( cat riot.doxyfile ; echo "GENERATE_HTML = yes" ) | doxygen -
.PHONY: man
-man:
+man: src/changelog.md
( cat riot.doxyfile ; echo "GENERATE_MAN = yes" ) | doxygen -
ifneq (,$(shell which lessc))
@@ -27,9 +27,12 @@ src/css/variables.less: src/config.json
-e 's/",\?$$/;/g' -e 's/\\"/"/g' > $@
endif
+src/changelog.md: src/changelog.md.tmp ../../release-notes.txt
+ @./generate-changelog.py $+ $@
+
.PHONY:
-latex:
+latex: src/changelog.md
( cat riot.doxyfile ; echo "GENERATE_LATEX= yes" ) | doxygen -
clean:
- -@rm -rf latex man html doxygen_objdb_*.tmp doxygen_entrydb_*.tmp
+ -@rm -rf latex man html doxygen_objdb_*.tmp doxygen_entrydb_*.tmp src/changelog.md
diff --git a/doc/doxygen/generate-changelog.py b/doc/doxygen/generate-changelog.py
new file mode 100755
index 0000000000..2e35e4e702
--- /dev/null
+++ b/doc/doxygen/generate-changelog.py
@@ -0,0 +1,66 @@
+#! /usr/bin/env python
+# -*- coding: utf-8 -*-
+# vim:fenc=utf-8
+#
+# Copyright © 2017 Martine Lenders <m.lenders@fu-berlin.de>
+#
+# Distributed under terms of the MIT license.
+
+from __future__ import print_function
+import re
+import sys
+
+def generate_changelog(template_filename, changelog_filename, output_filename):
+ with open(template_filename) as template, \
+ open(changelog_filename) as changelog, \
+ open(output_filename, "w") as output:
+ changelog_lines = []
+ release_title = re.compile(r"((RIOT-\d{4}\.\d{2} - Release Notes)|(Release 2013\.08))")
+ notes_template = re.compile(r"\[Notes\]")
+ first_title = True
+ title = 0
+ prev_newline = False
+ # Traverse changelog file line-wise
+ for line in changelog:
+ # Remove duplicate newlines
+ if line == "\n" and not prev_newline:
+ prev_newline = True
+ elif line == "\n" and prev_newline:
+ continue
+ else:
+ prev_newline = False
+ if title: # if a release title was previously detected
+ changelog_lines.append("\n") # Remove the underline
+ title = False
+ prev_newline = True # this introduces a newline, so count it
+ elif release_title.match(line):
+ # if line contains a release title
+ release_match = re.search(r"(\d{4}\.\d{2})", line)
+ assert(release_match != None)
+ # parse out release number
+ release = release_match.group(1)
+ title = "Release %s" % release
+ tag = "release-%s" % release.replace('.', '-')
+ # append as level 1 title with reference anchor tag
+ changelog_lines.append("# %s {#%s}\n" % (title ,tag))
+ title = True
+ first_title = False
+ else:
+ # append non-title log lines as verbatim (so notation is kept)
+ changelog_lines.append(" %s" % line)
+ for line in template:
+ # Traverse template file line-wise
+ if notes_template.match(line):
+ # if template string is matched: start adding changelog lines
+ for line_log in changelog_lines:
+ print(line_log, file=output, end="")
+ else:
+ # just print the template line
+ print(line, file=output, end="")
+
+if __name__ == "__main__":
+ if len(sys.argv) < 4:
+ print("usage %s <md template> <changelog> <output md>" % sys.argv[0], file=sys.stderr)
+ sys.exit(1)
+ generate_changelog(sys.argv[1], sys.argv[2], sys.argv[3])
+
diff --git a/doc/doxygen/riot.doxyfile b/doc/doxygen/riot.doxyfile
index 677db136d0..493c165c5a 100644
--- a/doc/doxygen/riot.doxyfile
+++ b/doc/doxygen/riot.doxyfile
@@ -764,7 +764,8 @@ INPUT = ../../doc.txt \
src/mainpage.md \
src/creating-modules.md \
src/creating-an-application.md \
- src/getting-started.md
+ src/getting-started.md \
+ src/changelog.md
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
diff --git a/doc/doxygen/src/changelog.md.tmp b/doc/doxygen/src/changelog.md.tmp
new file mode 100644
index 0000000000..acff108ce0
--- /dev/null
+++ b/doc/doxygen/src/changelog.md.tmp
@@ -0,0 +1,6 @@
+Changelog {#changelog}
+=========
+
+[TOC]
+
+[Notes]
--
GitLab