From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 7871) id E500F3858C50; Thu, 1 Dec 2022 13:54:49 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org E500F3858C50 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1669902889; bh=ZrpnXrZsca36gVitPaRHFHNbqOy2NIel2unqj02tjvI=; h=From:To:Subject:Date:From; b=P/YX7NubtHdcINOHYJnL2Ww8cnprNpIXnSqOTfZ+oJ2YrfWiQa3zN3fdd/2R9q/6L yNal47PAfTeeCpg9AOLEHqw5MSOWIH8tC5fBoQgMXVqm/DNHE3pw5TH93KzlmvlhGj 8dI+K9onKhEjbkRoyfjDASoiOLj5NNC3eJBGWq4Y= MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset="utf-8" From: Marc Poulhi?s To: gcc-cvs@gcc.gnu.org Subject: [gcc r13-4439] ada: Minor updates to gnat/doc configuration X-Act-Checkin: gcc X-Git-Author: Josue Nava Bello X-Git-Refname: refs/heads/master X-Git-Oldrev: ecc363971aeac52481d92de8b37521f6cc2d38e6 X-Git-Newrev: 3217d7d7aedcb804dc7cc1bf9f25552a9af41c41 Message-Id: <20221201135449.E500F3858C50@sourceware.org> Date: Thu, 1 Dec 2022 13:54:49 +0000 (GMT) List-Id: https://gcc.gnu.org/g:3217d7d7aedcb804dc7cc1bf9f25552a9af41c41 commit r13-4439-g3217d7d7aedcb804dc7cc1bf9f25552a9af41c41 Author: Josue Nava Bello Date: Mon Nov 14 13:45:27 2022 +0000 ada: Minor updates to gnat/doc configuration Minor updates to conf.py (comments, indentation) gcc/ada/ * doc/share/conf.py: minor updates Diff: --- gcc/ada/doc/share/conf.py | 100 +++++++++++++++++++++++++++++++++------------- 1 file changed, 72 insertions(+), 28 deletions(-) diff --git a/gcc/ada/doc/share/conf.py b/gcc/ada/doc/share/conf.py index 9ab80e7759e..48f1a96a309 100644 --- a/gcc/ada/doc/share/conf.py +++ b/gcc/ada/doc/share/conf.py @@ -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)