1
2
3
4
5
6
7
8
9
10
11
12
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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
|
# Copyright 2018 Virgil Dupras
#
# This software is licensed under the "GPLv3" License as described in the "LICENSE" file,
# which should be included with this package. The terms are also available at
# http://www.gnu.org/licenses/gpl-3.0.html
from pathlib import Path
import re
from typing import Callable, Dict, Union
from hscommon.build import read_changelog_file, filereplace
from sphinx.cmd.build import build_main as sphinx_build
CHANGELOG_FORMAT = """
{version} ({date})
----------------------
{description}
"""
def tixgen(tixurl: str) -> Callable[[str], str]:
"""This is a filter *generator*. tixurl is a url pattern for the tix with a {0} placeholder
for the tix #
"""
urlpattern = tixurl.format("\\1") # will be replaced buy the content of the first group in re
R = re.compile(r"#(\d+)")
repl = f"`#\\1 <{urlpattern}>`__"
return lambda text: R.sub(repl, text)
def gen(
basepath: Path,
destpath: Path,
changelogpath: Path,
tixurl: str,
confrepl: Union[Dict[str, str], None] = None,
confpath: Union[Path, None] = None,
changelogtmpl: Union[Path, None] = None,
) -> None:
"""Generate sphinx docs with all bells and whistles.
basepath: The base sphinx source path.
destpath: The final path of html files
changelogpath: The path to the changelog file to insert in changelog.rst.
tixurl: The URL (with one formattable argument for the tix number) to the ticket system.
confrepl: Dictionary containing replacements that have to be made in conf.py. {name: replacement}
"""
if confrepl is None:
confrepl = {}
if confpath is None:
confpath = Path(basepath, "conf.tmpl")
if changelogtmpl is None:
changelogtmpl = Path(basepath, "changelog.tmpl")
changelog = read_changelog_file(changelogpath)
tix = tixgen(tixurl)
rendered_logs = []
for log in changelog:
description = tix(log["description"])
# The format of the changelog descriptions is in markdown, but since we only use bulled list
# and links, it's not worth depending on the markdown package. A simple regexp suffice.
description = re.sub(r"\[(.*?)\]\((.*?)\)", "`\\1 <\\2>`__", description)
rendered = CHANGELOG_FORMAT.format(version=log["version"], date=log["date_str"], description=description)
rendered_logs.append(rendered)
confrepl["version"] = changelog[0]["version"]
changelog_out = Path(basepath, "changelog.rst")
filereplace(changelogtmpl, changelog_out, changelog="\n".join(rendered_logs))
if Path(confpath).exists():
conf_out = Path(basepath, "conf.py")
filereplace(confpath, conf_out, **confrepl)
# Call the sphinx_build function, which is the same as doing sphinx-build from cli
try:
sphinx_build([str(basepath), str(destpath)])
except SystemExit:
print("Sphinx called sys.exit(), but we're cancelling it because we don't actually want to exit")
|
