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)
|