summaryrefslogtreecommitdiff
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
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
-rw-r--r--Pipfile1
-rw-r--r--Pipfile.lock26
-rw-r--r--source/conf.py43
-rw-r--r--source/index.rst6
4 files changed, 67 insertions, 9 deletions
diff --git a/Pipfile b/Pipfile
index 3aeefbe..d8026a3 100644
--- a/Pipfile
+++ b/Pipfile
@@ -5,6 +5,7 @@ name = "pypi"
[packages]
sphinx = "*"
+GitPython = "*"
[dev-packages]
diff --git a/Pipfile.lock b/Pipfile.lock
index 2698239..c7f5957 100644
--- a/Pipfile.lock
+++ b/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",
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.