summaryrefslogtreecommitdiff
path: root/source
diff options
context:
space:
mode:
authorJan Dittberner <jandd@cacert.org>2018-10-27 01:21:25 +0200
committerJan Dittberner <jandd@cacert.org>2018-10-27 01:21:25 +0200
commitd0a2424a211fbd22c88ea1315f6cf51c1cd84039 (patch)
tree149d23cc3f1bd69df5556fd1c5f1c8971efdd9af /source
parente9600db4861100317436190b0630b0094f58f5ef (diff)
downloadcacert-codedocs-d0a2424a211fbd22c88ea1315f6cf51c1cd84039.tar.gz
cacert-codedocs-d0a2424a211fbd22c88ea1315f6cf51c1cd84039.tar.xz
cacert-codedocs-d0a2424a211fbd22c88ea1315f6cf51c1cd84039.zip
Add minor improvements for documentation build
- add git version to generated output - fix broken headline - add support for wiki links and bug tracker links
Diffstat (limited to 'source')
-rw-r--r--source/conf.py43
-rw-r--r--source/index.rst6
2 files changed, 41 insertions, 8 deletions
diff --git a/source/conf.py b/source/conf.py
index f3594d8..a80f538 100644
--- a/source/conf.py
+++ b/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)
diff --git a/source/index.rst b/source/index.rst
index 465de44..bb39a6d 100644
--- a/source/index.rst
+++ b/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.