xref: /petsc/doc/conf.py (revision 5815e746ee9772c581ab1ae48524efeb0066b819) 
1# Configuration file for the Sphinx documentation builder.
2#
3# For information on options, see
4#   http://www.sphinx-doc.org/en/master/config
5#
6# You may also find it helpful to run "sphinx-quickstart" in a scratch
7# directory and read the comments in the automatically-generated conf.py file.
8
9import os
10import sys
11import subprocess
12import re
13import datetime
14
15sys.path.append(os.getcwd())
16sys.path.append(os.path.abspath('./ext'))
17
18import add_version_header
19import build_classic_docs
20import make_links_relative
21
22
23if not os.path.isdir("images"):
24    print("-----------------------------------------------------------------------------")
25    print("ERROR")
26    print("images directory does not seem to exist.")
27    print("To clone the required repository, try")
28    print("   make images")
29    print("-----------------------------------------------------------------------------")
30    raise Exception("Aborting because images missing")
31
32
33# -- Project information -------------------------------------------------------
34
35project = 'PETSc'
36copyright = '1991-%d, UChicago Argonne, LLC and the PETSc Development Team' % datetime.date.today().year
37author = 'The PETSc Development Team'
38
39with open(os.path.join('..', 'include', 'petscversion.h'),'r') as version_file:
40    buf = version_file.read()
41    petsc_release_flag = re.search(' PETSC_VERSION_RELEASE[ ]*([0-9]*)',buf).group(1)
42    major_version      = re.search(' PETSC_VERSION_MAJOR[ ]*([0-9]*)',buf).group(1)
43    minor_version      = re.search(' PETSC_VERSION_MINOR[ ]*([0-9]*)',buf).group(1)
44    subminor_version   = re.search(' PETSC_VERSION_SUBMINOR[ ]*([0-9]*)',buf).group(1)
45
46    git_describe_version = subprocess.check_output(['git', 'describe', '--always']).strip().decode('utf-8')
47    if petsc_release_flag == '0':
48        version = git_describe_version
49        release = git_describe_version
50    else:
51        version = '.'.join([major_version, minor_version])
52        release = '.'.join([major_version,minor_version,subminor_version])
53
54
55# -- General configuration -----------------------------------------------------
56
57needs_sphinx='3.5'
58nitpicky = True  # checks internal links. For external links, use "make linkcheck"
59master_doc = 'index'
60templates_path = ['_templates']
61exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
62highlight_language = 'c'
63numfig = True
64
65# -- Extensions ----------------------------------------------------------------
66
67extensions = [
68    'sphinx_copybutton',
69    'sphinx_panels',
70    'sphinxcontrib.bibtex',
71    'sphinxcontrib.katex',
72    'sphinxcontrib.rsvgconverter',
73    'html5_petsc',
74]
75
76copybutton_prompt_text = r"[>]{1,3}"
77copybutton_prompt_is_regexp = True
78
79bibtex_bibfiles = [
80        os.path.join('..', 'src', 'docs', 'tex', 'petsc.bib'),
81        os.path.join('..', 'src', 'docs', 'tex', 'petscapp.bib'),
82        os.path.join('..', 'src', 'docs', 'tao_tex', 'tao.bib'),
83        os.path.join('..', 'src', 'docs', 'tao_tex', 'manual', 'mathprog.bib'),
84        ]
85
86
87# -- Options for HTML output ---------------------------------------------------
88
89html_theme = 'pydata_sphinx_theme'
90
91html_theme_options = {
92    "icon_links": [
93        {
94            "name": "GitLab",
95            "url": "https://gitlab.com/petsc/petsc",
96            "icon": "fab fa-gitlab",
97        },
98    ],
99    "use_edit_page_button": True,
100    "footer_items": ["copyright", "sphinx-version", "last-updated"],
101}
102
103html_context = {
104    "github_url": "https://gitlab.com",
105    "github_user": "petsc",
106    "github_repo": "petsc",
107    "github_version": "release",
108    "doc_path": "doc",
109}
110
111html_static_path = ['_static']
112html_logo = os.path.join('images', 'logos', 'PETSc_TAO_logos', 'PETSc-TAO', 'web', 'PETSc-TAO_RGB.svg')
113html_favicon = os.path.join('images', 'logos', 'PETSc_TAO_logos', 'PETSc', 'petsc_favicon.png')
114html_last_updated_fmt = r'%Y-%m-%dT%H:%M:%S%z (' + git_describe_version + ')'
115
116
117
118# -- Options for LaTeX output --------------------------------------------------
119latex_engine = 'xelatex'
120
121# How to arrange the documents into LaTeX files, building only the manual.
122latex_documents = [
123        ('docs/manual/index', 'manual.tex', 'PETSc/TAO Users Manual', author, 'manual', False)
124        ]
125
126latex_additional_files = [
127    'docs/manual/anl_tech_report/ArgonneLogo.pdf',
128    'docs/manual/anl_tech_report/ArgonneReportTemplateLastPage.pdf',
129    'docs/manual/anl_tech_report/ArgonneReportTemplatePage2.pdf',
130    'docs/manual/anl_tech_report/first.inc',
131    'docs/manual/anl_tech_report/last.inc',
132]
133
134latex_elements = {
135    'maketitle': r'\newcommand{\techreportversion}{%s}' % version +
136r'''
137\input{first.inc}
138''',
139    'printindex': r'''
140\printindex
141\input{last.inc}
142''',
143    'fontpkg': r'''
144\setsansfont{DejaVu Sans}
145\setmonofont{DejaVu Sans Mono}
146''',
147    'tableofcontents' : r''
148}
149
150
151# -- Setup and event callbacks -------------------------------------------------
152
153# Trigger a build of the "classic" docs
154def _build_classic_docs(app):
155    build_classic_docs.main()
156
157
158def builder_init_handler(app):
159    _build_classic_docs(app)
160
161
162def _add_version_header(app, exception):
163    if exception is None and app.builder.name.endswith('html'):
164        print("============================================")
165        print("    Adding version to classic man pages, from conf.py")
166        print("============================================")
167        add_version_header.add_version_header(os.path.join(app.outdir, "docs", "manualpages"), release)
168
169
170def _copy_classic_docs(app, exception):
171    if exception is None and app.builder.name.endswith('html'):
172        print("============================================")
173        print("    Copying classic docs from conf.py       ")
174        print("============================================")
175        build_classic_docs.copy_classic_docs(app.outdir)
176
177
178def _fix_links(app, exception):
179    if exception is None and app.builder.name.endswith('html'):
180        print("============================================")
181        print("    Fixing relative links from conf.py      ")
182        print("============================================")
183        make_links_relative.make_links_relative(app.outdir)
184
185
186def build_finished_handler(app, exception):
187    _copy_classic_docs(app, exception)
188    _fix_links(app, exception)
189    _add_version_header(app, exception)
190
191
192def setup(app):
193    app.connect('builder-inited', builder_init_handler)
194    app.connect('build-finished', build_finished_handler)
195    app.add_css_file('css/pop-up.css')
196