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.