conf.py 3.57 KB
Newer Older
Rahix's avatar
Rahix committed
1
2
3
4
5
6
7
8
9
10
11
import os
import subprocess
import sys
import time
import sphinx.util.logging

# If extensions (or modules to document with autodoc) are in another directory,
# 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.
#
sys.path.insert(0, os.path.abspath("../pycardium/modules/py"))
ch3's avatar
ch3 committed
12
sys.path.insert(0, os.path.abspath("./"))
Rahix's avatar
Rahix committed
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

logger = sphinx.util.logging.getLogger("card10/conf.py")


# -- Project information -----------------------------------------------------

project = "card10-firmware"
copyright = "2019"

# The full version, including alpha/beta/rc tags
release = subprocess.check_output(
    ["git", "describe", "--long", "--always"]
).decode().strip()
release += "<br />"
release += time.strftime("%F %R")
version = release


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.viewcode",
    "sphinx.ext.ifconfig",
Rahix's avatar
Rahix committed
40
    "sphinx.ext.todo",
Rahix's avatar
Rahix committed
41
42
]

Rahix's avatar
Rahix committed
43
44
todo_include_todos = True

Rahix's avatar
Rahix committed
45
46
47
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
ch3's avatar
ch3 committed
48
exclude_patterns = ["output", "Thumbs.db", ".DS_Store", "hawkmoth"]
Rahix's avatar
Rahix committed
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

# -- Options for HTML output ------------------------------------------------- {{{

# The Read the Docs theme is available from
# - https://github.com/snide/sphinx_rtd_theme
# - https://pypi.python.org/pypi/sphinx_rtd_theme
# - python-sphinx-rtd-theme package (on Debian)
try:
    import sphinx_rtd_theme
    html_theme = "sphinx_rtd_theme"
    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
    pygments_style = "monokai"
except ImportError:
    logger.warning("The Sphinx \"sphinx_rtd_theme\" HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.")


# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["static"]
Rahix's avatar
Rahix committed
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

# Theme Options
html_theme_options = {
    "style_external_links": True,
}

# Show "Edit on GitLab" links
html_show_sourcelink = False
html_context = {
    "display_gitlab": True,
    "gitlab_host": "git.card10.badge.events.ccc.de",
    "gitlab_user": "card10",
    "gitlab_repo": "firmware",
    "gitlab_version": "master/",
    "conf_py_path": "Documentation/",
    "theme_vcs_pageview_mode": "edit",
}
Rahix's avatar
Rahix committed
86
87
88
89
# }}}

# -- Options for Auto-Doc ---------------------------------------------------- {{{
autodoc_mock_imports = [
Gerd's avatar
Gerd committed
90
    "sys_display",
Rahix's avatar
Rahix committed
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
    "ucollections",
    "urandom",
    "utime",
]

autodoc_member_order = "bysource"
# }}}

# -- Options for Hawkmoth ---------------------------------------------------- {{{
has_hawkmoth = False
try:
    # Attempt importing hawkmoth
    import hawkmoth  # noqa: F401
    extensions.append("hawkmoth")

    cautodoc_root = os.path.abspath("..")
Rahix's avatar
Rahix committed
107
    cautodoc_clang = "-D__SPHINX_DOC"
Rahix's avatar
Rahix committed
108
    has_hawkmoth = True
ch3's avatar
ch3 committed
109
110
111
except ImportError as e:
    if e.name == "clang":
        logger.warning("hawkmoth requires the clang python module.  Documentation for Epicardium API will not be generated.")
Rahix's avatar
Rahix committed
112
113
114
115
116
117
# }}}


# -- Sphinx Setup ------------------------------------------------------------
def setup(app):
    app.add_config_value("has_hawkmoth", has_hawkmoth, "")