@@ -2,6 +2,9 @@
# Style_Check:Python_Fragment (meaning no pyflakes check)
#
# GNAT build configuration file
+# --------------------------------
+# This file defines the configuration for all files created
+# by Sphinx. In this case, pdf (using latex) and html
import sys
import os
@@ -13,16 +16,12 @@ sys.path.append('.')
import ada_pygments
import latex_elements
-# Some configuration values for the various documentation handled by
-# this conf.py
-
+# Define list of documents to be built and their title
DOCS = {
- 'gnat_rm': {
- 'title': 'GNAT Reference Manual'},
- 'gnat_ugn': {
- 'title': 'GNAT User\'s Guide for Native Platforms'},
- 'gnat-style': {
- 'title': 'GNAT Coding Style: A Guide for GNAT Developers'}}
+ "gnat_rm": {"title": "GNAT Reference Manual"},
+ "gnat_ugn": {"title": "GNAT User's Guide for Native Platforms"},
+ "gnat-style": {"title": "GNAT Coding Style: A Guide for GNAT Developers"},
+}
# Then retrieve the source directory
root_source_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
@@ -30,14 +29,17 @@ gnatvsn_spec = os.path.join(root_source_dir, '..', 'gnatvsn.ads')
basever = os.path.join(root_source_dir, '..', '..', 'BASE-VER')
texi_fsf = True # Set to False when FSF doc is switched to sphinx by default
+# get vsn specs
with open(gnatvsn_spec, 'r') as fd:
gnatvsn_content = fd.read()
+# read copyright test from .rst file (used also for sanity-checking)
def get_copyright():
return '2008-%s, Free Software Foundation' % time.strftime('%Y')
+# get environment gnat version (used also for sanity-checking)
def get_gnat_version():
m = re.search(r'Gnat_Static_Version_String : ' +
r'constant String := "([^\(\)]+)\(.*\)?";',
@@ -58,6 +60,7 @@ def get_gnat_version():
sys.exit(1)
+# get gnat build type from runtime
def get_gnat_build_type():
m = re.search(r'Build_Type : constant Gnat_Build_Type := (.+);',
gnatvsn_content)
@@ -70,7 +73,35 @@ def get_gnat_build_type():
sys.exit(1)
+# Enable Sphinx extensions
+# Note that these are active for all files to be build (see DOCS list)
+extensions = ['sphinx_rtd_theme']
+
+# todo interprets ".. todo::" commands in .rst files
+# mathjax enables math equations to render correctly
+extensions += ['sphinx.ext.todo', 'sphinx.ext.mathjax']
+todo_include_todos = True
+
+# define templates source folder
+templates_path = ['_templates']
+# define the types of files to read as source for documents
+source_suffix = '.rst'
+
+# enable figure, object, table numeration on documents
+print('enabling table, code-block and figure numeration')
+numfig = True
+numfig_format = {
+ 'figure': 'figure %s',
+ 'table': 'table %s',
+ 'code-block': 'listing %s',
+ 'section': 'section %s',
+}
+print('done')
+
+
+# Start building the documents
# First retrieve the name of the documentation we are building
+print('checking doc name... ')
doc_name = os.environ.get('DOC_NAME', None)
if doc_name is None:
print('DOC_NAME environment variable should be set')
@@ -79,7 +110,7 @@ if doc_name is None:
if doc_name not in DOCS:
print('%s is not a valid documentation name' % doc_name)
sys.exit(1)
-
+print('found... ' , doc_name)
# Exclude sources that are not part of the current documentation
exclude_patterns = []
@@ -88,16 +119,13 @@ for d in os.listdir(root_source_dir):
exclude_patterns.append(d)
print('ignoring %s' % d)
+# Special condition for gnat_rm
if doc_name == 'gnat_rm':
exclude_patterns.append('share/gnat_project_manager.rst')
print('ignoring share/gnat_project_manager.rst')
-extensions = ['sphinx_rtd_theme']
-templates_path = ['_templates']
-source_suffix = '.rst'
-master_doc = doc_name
-
# General information about the project.
+master_doc = doc_name
project = DOCS[doc_name]['title']
copyright = get_copyright()
@@ -107,42 +135,58 @@ release = get_gnat_version()
pygments_style = None
tags.add(get_gnat_build_type())
+
+# Define figures to be included
html_theme = 'sphinx_rtd_theme'
if os.path.isfile('adacore_transparent.png'):
+ # split html and pdf logos to avoid 'same name' error in sphinx <5.2+
html_logo = 'adacore_transparent.png'
+ latex_logo = 'adacore_transparent.png'
if os.path.isfile('favicon.ico'):
html_favicon = 'favicon.ico'
html_static_path = ['_static']
+# Use gnat.sty for bulding documents
latex_additional_files = ['gnat.sty']
+# Add copyright info to file
copyright_macros = {
'date': time.strftime("%b %d, %Y"),
'edition': 'GNAT %s Edition' % 'Pro' if get_gnat_build_type() == 'PRO'
else 'GPL',
'name': 'GNU Ada',
'tool': 'GNAT',
- 'version': version}
+ 'version': version
+}
+# Send info to latex for building document
latex_elements = {
- 'preamble': '\\usepackage{gnat}\n' +
- latex_elements.TOC_DEPTH +
- latex_elements.PAGE_BLANK +
- latex_elements.TOC_CMD +
- latex_elements.LATEX_HYPHEN +
- latex_elements.doc_settings(DOCS[doc_name]['title'],
- get_gnat_version()),
- 'tableofcontents': latex_elements.TOC % copyright_macros}
-
+ 'preamble': '\\usepackage{gnat}\n' # use gnat.sty format
+ + latex_elements.TOC_DEPTH # define table of contents max depth to display
+ + latex_elements.PAGE_BLANK # define blank pages and when to be used
+ + latex_elements.TOC_CMD # write table of contents
+ + latex_elements.LATEX_HYPHEN # define latex hyphen '-'
+ + '\\sloppy\n\n' # sloppy/fussy define how words are spread in a paragraph
+ # the following is used to send title and gnat version to latex
+ + latex_elements.doc_settings(DOCS[doc_name]['title'], get_gnat_version()),
+ 'tableofcontents': latex_elements.TOC % copyright_macros, # build TOC
+ 'papersize': 'a4paper,table', # papersize as a4, else default letter
+ 'figure_align': 'H', # align figure as square and to paragraph text
+ 'maketitle': '\\maketitle', # execute custom maketitle
+}
+
+# Show page references for cross-reference in docs
+latex_show_pagerefs = True
+# Define latex metadata
latex_documents = [
(master_doc, '%s.tex' % doc_name, project, 'AdaCore', 'manual')]
-
+# Define .txt files metadata
texinfo_documents = [
- (master_doc, doc_name, project,
- 'AdaCore', doc_name, doc_name, '')]
+ (master_doc, doc_name, project, 'AdaCore', doc_name, doc_name, '')]
+# setup AdaCore custom pygments
def setup(app):
app.add_lexer('ada', ada_pygments.AdaLexer)
app.add_lexer('gpr', ada_pygments.GNATProjectLexer)