generate bug description page not by gradle but by sphinx extension

Previously we needed to commit generated files to Git,
because readthedocs does not support executing Gradle script before
we build HTML pages.
By this change, we can stop commiting them to Git,
it also makes possible to translate not only short/long descriptions
but also detailed description.

docs/.gitignore

@@ -1 +1,4 @@
 .build
+*.pyc
+generated/*.rst
+locale/ja/LC_MESSAGES/generated/*.po

docs/Dockerfile

@@ -12,7 +12,7 @@ RUN curl -kL https://bootstrap.pypa.io/get-pip.py | python
 
 RUN pip install sphinx-intl
 
-WORKDIR /documents
+WORKDIR /documents/docs
 VOLUME /documents
 
 CMD ["/bin/bash"]

docs/build.sh

@@ -4,10 +4,10 @@ docker build -t spotbugs-sphinx .
 rm -rf .build
 
 # extract messages from base document (en) to .pot files
-docker run -it -v $(pwd):/documents spotbugs-sphinx make gettext
+docker run -it -v $(pwd)/..:/documents spotbugs-sphinx make gettext
 
 # build .po files by new .pot files
-docker run -it -v $(pwd):/documents spotbugs-sphinx sphinx-intl update -p .build/locale -l ja
+docker run -it -v $(pwd)/..:/documents spotbugs-sphinx sphinx-intl update -p .build/locale -l ja
 
 # build html files
-docker run -it -v $(pwd):/documents spotbugs-sphinx make html
+docker run -it -v $(pwd)/..:/documents spotbugs-sphinx make html

docs/conf.py

@@ -269,4 +269,7 @@
 gettext_compact = False
 
 def setup(app):
-  app.add_stylesheet('custom.css')
+    app.add_stylesheet('custom.css')
+
+sys.path.append(os.path.abspath('extensions'))
+extensions += ['generate_bug_description']

docs/extensions/generate_bug_description.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+# A Sphinx extension to generate list of bug descriptions from findbugs.xml and messages.xml.
+# It is necessary to generate localized list, because Sphinx i18n feature based on .po file
+# does not support translating raw HTML block.
+
+from xml.etree.ElementTree import *
+import codecs
+
+def generate_category_title(bug_category):
+    return "%s (%s)" % (bug_category.findtext('.//Description'), bug_category.get('category'))
+
+def generate_pattern_title(bug_pattern, message):
+    return "%s: %s (%s)" % (bug_pattern.get('abbrev'), message.findtext('.//ShortDescription'), bug_pattern.get('type'))
+
+def generate_bug_description(language):
+    print("Generating bug description page for %s..." % language)
+    findbugs = parse('../spotbugs/etc/findbugs.xml')
+    if language == 'ja':
+        messages = parse('../spotbugs/etc/messages_ja.xml')
+    else:
+        messages = parse('../spotbugs/etc/messages.xml')
+
+    with codecs.open('generated/bugDescriptionList.rst', 'w', encoding='UTF-8') as bug_description_page:
+        for bug_category in sorted(messages.getiterator('BugCategory'), key=lambda element: element.get('category')):
+            category = bug_category.get('category')
+            category_title = generate_category_title(bug_category)
+            bug_description_page.write(category_title)
+            bug_description_page.write('\n')
+            bug_description_page.write('-' * len(category_title))
+            bug_description_page.write('\n')
+            for line in bug_category.findtext('.//Details').splitlines():
+                bug_description_page.write(line.strip())
+                bug_description_page.write('\n')
+            bug_description_page.write('\n\n')
+
+            for bug_pattern in findbugs.findall(".//BugPattern[@category='%s']" % category):
+                type = bug_pattern.get('type')
+                message = messages.find(".//BugPattern[@type='%s']" % type)
+                pattern_title = generate_pattern_title(bug_pattern, message)
+                bug_description_page.write("%s\n%s\n\n" % (pattern_title, '^' * len(pattern_title)))
+                details = message.findtext('.//Details')
+                bug_description_page.write('.. raw:: html\n')
+                for line in details.splitlines():
+                    bug_description_page.write('  ')
+                    bug_description_page.write(line)
+                    bug_description_page.write('\n')
+                bug_description_page.write('\n')
+
+def setup(app):
+    app.connect('builder-inited', lambda app: generate_bug_description(app.config.language))

docs/generated/README.md

@@ -1,5 +1 @@
-This directory stores generated files, which is necessary to commit to Git due to limitation of ReadTheDocs.
-Currently readthedocs.org has no feature to trigger build tool like Gradle.
-So it's necessary to commit generated files too.
-
-For detail about generation process, check `/docs/build.gradle`
+This directory stores generated files. For detail about generation process, check `/docs/build.sh`