File: conf.py

package info (click to toggle)
mpich 4.0.2-3
  • links: PTS, VCS
  • area: main
  • in suites: bookworm
  • size: 423,384 kB
  • sloc: ansic: 1,088,434; cpp: 71,364; javascript: 40,763; f90: 22,829; sh: 17,463; perl: 14,773; xml: 14,418; python: 10,265; makefile: 9,246; fortran: 8,008; java: 4,355; asm: 324; ruby: 176; lisp: 19; php: 8; sed: 4
file content (153 lines) | stat: -rw-r--r-- 5,011 bytes parent folder | download | duplicates (2)
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
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
# -*- coding: utf-8 -*-
#
# Copyright (C) Mellanox Technologies Ltd. 2019.  ALL RIGHTS RESERVED.
# Copyright (C) Arm Ltd. 2021.  ALL RIGHTS RESERVED.
#
# See file LICENSE for terms.
#

#
# Project information
#

project   = u'OpenUCX'
copyright = u'2019, UCF'
author    = u'UCF'

#
# General options
#

extensions         = ['recommonmark', 'breathe'] # For processing Markdown pages
templates_path     = ['_templates']
source_suffix      = ['.rst', '.md']
master_doc         = 'index'
language           = None
exclude_patterns   = [u'_build']
pygments_style     = None

#
# Breathe configuration
#

# breathe_separate_member_pages      = False
# breathe_show_enumvalue_initializer = False
# breathe_show_define_initializer    = False
breathe_order_parameters_first     = True
breathe_projects = {"openucx":"build/xml/",}

#                  
# HTML options     
#                  

html_theme         = 'sphinx_rtd_theme'
html_logo          = '_static/ucxlogo.png'
html_theme_options = {
    'style_external_links': True
}
html_static_path   = ['_static']
htmlhelp_basename  = 'OpenUCXdoc'


#
# UCX custom configuration
#

# For the local testing set cached_version to the latest released version (e.g 'v1.10.1').
# Otherwise, GitHub may block you for a frequent access to GitHub API (DDOS protection).
cached_version = ''

def getLatestVersion():
    import requests

    global cached_version
    if cached_version == '':
        request = requests.get('https://api.github.com/repos/openucx/ucx/releases/latest')
        cached_version = request.json()["name"]

    return cached_version

def substituteVersion(app, docname, source):
    #
    # Updating these 2 variables will automatically update all download and API
    # documentation links.
    # We don't use the normal RST substitution because it cannot substitute text
    # inside code blocks and URL links.
    #
    version_name  = getLatestVersion()
    clean_version = version_name.lstrip('v')        # remove leading 'v' for tag name
    api_version   = clean_version.rsplit('.', 1)[0] # take only MAJOR.MINOR
    result        = source[0].replace("{VERSION}", api_version) \
                             .replace("{RELEASE}", clean_version)
    source[0] = result

def run_doxygen(doxygen_home):
    import subprocess, sys

    try:
        ret = subprocess.call('cd %s && doxygen && cd -' % doxygen_home, shell=True)
        if ret < 0:
            sys.stderr.write('doxygen error code %s' % (-ret))
    except OSError as e:
        sys.stderr.write('doxygen execution failed: %s' % e)

def run_apidoc(api_dir, xml_dir):
    import subprocess, sys

    try:
        # We don't generate groups since we create those manually
        ret = subprocess.call('breathe-apidoc -m -o %s -p openucx %s -g struct,file' % (api_dir, xml_dir), shell=True)
        if ret < 0:
            sys.stderr.write('breathe-apidoc error code %s' % (-ret))
    except OSError as e:
        sys.stderr.write('breathe-apidoc execution failed: %s' % e)

def config_doxygen_file(dox_dir, src_dir, output_dir):
    with open(dox_dir +'/ucxdox', 'r') as file :
        doxygenfile = file.read()
    # Using upstream doxygen configuration to generate "breathe" friendly
    # configration. Since autotools are not availible at RTD we are doing this
    # python way
    doxygenfile = doxygenfile.replace('$(PROJECT)', 'UCX')
    doxygenfile = doxygenfile.replace('$(VERSION)', getLatestVersion())
    doxygenfile = doxygenfile.replace('$(SRCDIR)', src_dir)
    doxygenfile = doxygenfile.replace('$(DOCDIR)', output_dir)
    doxygenfile = doxygenfile.replace('$(GENERATE_HTML)', 'NO')
    doxygenfile = doxygenfile.replace('$(GENERATE_HTMLHELP)', 'NO')
    doxygenfile = doxygenfile.replace('$(GENERATE_CHI)', 'NO')
    doxygenfile = doxygenfile.replace('$(GENERATE_LATEX)', 'NO')
    doxygenfile = doxygenfile.replace('$(GENERATE_RTF)', 'NO')
    doxygenfile = doxygenfile.replace('$(GENERATE_MAN)', 'NO')
    doxygenfile = doxygenfile.replace('$(GENERATE_XML)', 'YES')
    doxygenfile = doxygenfile.replace('$(PERL_PATH)', '/usr/bin/perl')
    doxygenfile = doxygenfile.replace('$(HAVE_DOT)', 'NO')
    doxygenfile = doxygenfile.replace('docs/doxygen/header.tex', '')
    # Exclude UCT documentation
    doxygenfile = doxygenfile.replace('../..//src/uct/api/', '')

    with open(dox_dir + '/Doxyfile', 'w') as file:
        file.write(doxygenfile)

def generate_api(app):
    import os

    read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
    if read_the_docs_build:
        dox_dir = '../doxygen'
        api_dir = 'api'
        xml_dir = 'build/xml/'
    else:
        dox_dir = 'doxygen'
        api_dir = 'source/api'
        xml_dir = 'source/build/xml/'

    output_dir = '../source/build'
    src_dir = '../../'

    config_doxygen_file(dox_dir, src_dir, output_dir)
    run_doxygen(dox_dir)
    run_apidoc(api_dir, xml_dir)

def setup(app):
    app.connect('builder-inited', generate_api)
    app.connect('source-read', substituteVersion)