__init__.py 1.73 KB
Newer Older
Jakub Ružička's avatar
Jakub Ružička committed
1
2
3
"""
generate docs from apkg code/docstrings using mkdocs-macros-plugin
"""
Jakub Ružička's avatar
Jakub Ružička committed
4
5
import inspect

6
from apkg import COMPAT_LEVEL
Jakub Ružička's avatar
Jakub Ružička committed
7
from apkg import ex
Jakub Ružička's avatar
Jakub Ružička committed
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
from apkg import pkgstyle
from apkg.cli import cmd2mod
from pathlib import Path


BASE_PATH = Path(__file__).parent.parent
BASE_CODE_URL = "https://gitlab.nic.cz/packaging/apkg/-/blob/master/"
APKG_NEW_ISSUE_URL = "https://gitlab.nic.cz/packaging/apkg/-/issues/new"


def define_env(env):
    """
    this is available in docs using jinja2 templates
    """
    env.variables.pkgstyles = pkgstyle.PKGSTYLES
    env.variables.new_issue_url = APKG_NEW_ISSUE_URL
Jakub Ružička's avatar
Jakub Ružička committed
24
    env.variables.exceptions = get_exceptions()
25
    env.variables.compat_level = COMPAT_LEVEL
Jakub Ružička's avatar
Jakub Ružička committed
26
27
28
29
30
31
32

    @env.filter
    def relpath(path):
        return Path(path).relative_to(BASE_PATH)

    @env.filter
    def file_link(path):
33
34
35
36
37
38
        fn = Path(path)
        try:
            # full path can be passed (i.e. on Read the Docs)
            fn = Path(path).relative_to(BASE_PATH)
        except ValueError:
            pass
Jakub Ružička's avatar
Jakub Ružička committed
39
        return "[{fn}]({url}{fn})".format(
40
            fn=fn,
Jakub Ružička's avatar
Jakub Ružička committed
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
            url=BASE_CODE_URL)

    @env.filter
    def file_text(path):
        text = Path(path).open('r').read().strip()
        return "``` text\n%s\n```" % text

    @env.filter
    def mod_doc(modname):
        mod = __import__(modname, fromlist=[''])
        return mod.__doc__.strip()

    @env.filter
    def cmd_help(cmd):
        modname = 'apkg.commands.%s' % cmd2mod(cmd)
        return "``` text\n$> apkg %s --help\n\n%s\n```" % (
            cmd, mod_doc(modname))
Jakub Ružička's avatar
Jakub Ružička committed
58
59
60
61
62
63
64
65
66


def get_exceptions():
    """
    return all apkg exceptions sorted by exit_code
    """
    exs = [e for _, e in inspect.getmembers(ex, inspect.isclass)]
    exs.sort(key=lambda x: x.exit_code)
    return exs