Add minor improvements for documentation build

- add git version to generated output
- fix broken headline
- add support for wiki links and bug tracker links

Pipfile

@@ -5,6 +5,7 @@ name = "pypi"
 
 [packages]
 sphinx = "*"
+GitPython = "*"
 
 [dev-packages]
 

Pipfile.lock

@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "9212e6ee36e0c6b347140f5a95a0f8186d5943bd08307caa2751114697ce9024"
+            "sha256": "79ff5ee916caddd1a501ea9f2a89f04e6f4b7ace5aee173ebdbf80e5d49ea6de"
         },
         "pipfile-spec": 6,
         "requires": {
@@ -52,6 +52,22 @@
             ],
             "version": "==0.14"
         },
+        "gitdb2": {
+            "hashes": [
+                "sha256:83361131a1836661a155172932a13c08bda2db3674e4caa32368aa6eb02f38c2",
+                "sha256:e3a0141c5f2a3f635c7209d56c496ebe1ad35da82fe4d3ec4aaa36278d70648a"
+            ],
+            "markers": "python_version != '3.1.*' and python_version != '3.2.*' and python_version != '3.3.*' and python_version != '3.0.*' and python_version >= '2.7'",
+            "version": "==2.0.5"
+        },
+        "gitpython": {
+            "hashes": [
+                "sha256:563221e5a44369c6b79172f455584c9ebbb122a13368cc82cb4b5addff788f82",
+                "sha256:8237dc5bfd6f1366abeee5624111b9d6879393d84745a507de0fda86043b65a8"
+            ],
+            "index": "pypi",
+            "version": "==2.1.11"
+        },
         "idna": {
             "hashes": [
                 "sha256:156a6814fb5ac1fc6850fb002e0852d56c0c8d2531923a51032d1b70760e186e",
@@ -125,6 +141,14 @@
             ],
             "version": "==1.11.0"
         },
+        "smmap2": {
+            "hashes": [
+                "sha256:0555a7bf4df71d1ef4218e4807bbf9b201f910174e6e08af2e138d4e517b4dde",
+                "sha256:29a9ffa0497e7f2be94ca0ed1ca1aa3cd4cf25a1f6b4f5f87f74b46ed91d609a"
+            ],
+            "markers": "python_version != '3.1.*' and python_version != '3.2.*' and python_version != '3.3.*' and python_version != '3.0.*' and python_version >= '2.7'",
+            "version": "==2.0.5"
+        },
         "snowballstemmer": {
             "hashes": [
                 "sha256:919f26a68b2c17a7634da993d91339e288964f93c274f1343e3bbbe2096e1128",

source/conf.py

@@ -12,10 +12,12 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+from datetime import datetime
 import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+from git import repo
 
 # -- Project information -----------------------------------------------------
 
@@ -24,9 +26,12 @@ copyright = '2018, CAcert development team'
 author = 'CAcert development team'
 
 # The short X.Y version
-version = ''
+version = '0.1'
 # The full version, including alpha/beta/rc tags
-release = ''
+release = "{}-git:{} built:{}".format(
+        version,
+        repo.Repo('..').git.describe('--always', '--dirty'),
+        datetime.utcnow().replace(microsecond=0))
 
 
 # -- General configuration ---------------------------------------------------
@@ -40,6 +45,7 @@ release = ''
 # ones.
 extensions = [
     'sphinx.ext.intersphinx',
+    'sphinx.ext.extlinks',
     'sphinx.ext.todo',
     'sphinx.ext.ifconfig',
 ]
@@ -89,6 +95,8 @@ html_theme_options = {
     'sidebarlinkcolor': '#005fa9',
 }
 
+html_title = project + " v" + release
+
 html_logo = os.path.join('images', 'CAcert-logo-colour.svg')
 
 html_favicon = os.path.join('images', 'favicon.ico')
@@ -139,7 +147,7 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'CAcertcodedocumentation.tex', 'CAcert code documentation Documentation',
+    (master_doc, 'CAcertcodedocumentation.tex', 'CAcert code documentation',
      'CAcert development team', 'manual'),
 ]
 
@@ -149,7 +157,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'cacertcodedocumentation', 'CAcert code documentation Documentation',
+    (master_doc, 'cacertcodedocumentation', 'CAcert code documentation',
      [author], 1)
 ]
 
@@ -160,7 +168,7 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'CAcertcodedocumentation', 'CAcert code documentation Documentation',
+    (master_doc, 'CAcertcodedocumentation', 'CAcert code documentation',
      author, 'CAcertcodedocumentation', 'One line description of project.',
      'Miscellaneous'),
 ]
@@ -195,3 +203,28 @@ intersphinx_mapping = {'https://docs.python.org/': None}
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
+
+extlinks = {
+    'wiki': ('https://wiki.cacert.org/%s', 'Wiki '),
+}
+
+
+def cacert_bug(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    try:
+        bugnum = int(text)
+        if bugnum <= 0:
+            raise ValueError
+    except ValueError:
+        msg = inliner.reporter.error(
+            'Bug number must be a number greater than or equal to 1; '
+            '"%s" is invalid.' % text, line=lineno)
+        prb = inliner.problematic(rawtext, rawtext, msg)
+        return [prb], [msg]
+    ref = 'https://bugs.cacert.org/view.php?id=%d' % bugnum
+    node = nodes.reference(rawtext, '#' + utils.unescape(text), refuri=ref,
+                           **options)
+    return [node], []
+
+
+def setup(app):
+    app.add_role('bug', cacert_bug)

source/index.rst

@@ -1,10 +1,10 @@
-.. CAcert code documentation documentation master file, created by
+.. CAcert code documentation master file, created by
    sphinx-quickstart on Fri Oct 26 23:40:43 2018.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to CAcert code documentation's documentation!
+Welcome to CAcert code documentation
-=====================================================
+====================================
 
 This is a work in progress documentation of the CAcert web application source
 code at https://git.cacert.org/gitweb/?p=cacert.git.