From patchwork Thu Dec 1 13:55:05 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: =?utf-8?q?Marc_Poulhi=C3=A8s?= X-Patchwork-Id: 61312 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 5D89B38582A3 for ; Thu, 1 Dec 2022 13:55:40 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 5D89B38582A3 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1669902940; bh=QHPqpMFcDcHae9/3me6M7gzbX2E/Ih6ktDpFzDTxJ3w=; h=To:Cc:Subject:Date:List-Id:List-Unsubscribe:List-Archive: List-Post:List-Help:List-Subscribe:From:Reply-To:From; b=omnuGQjiVQRvNp4dSA6gGOslipbPL6e83Xu4N1S94agAyd5GvWBWLFOu8pSfileZH zqah5OkyNxy47bhotmRTMowJ97KXrONP41nmEqz+RimsQZHWsE0nO/6IjcJq74alsh LYG4dstZ6/5WjkhT2iW5gD2OzJW44tFPuW8DZimI= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from mail-wm1-x331.google.com (mail-wm1-x331.google.com [IPv6:2a00:1450:4864:20::331]) by sourceware.org (Postfix) with ESMTPS id B4B363858296 for ; Thu, 1 Dec 2022 13:55:10 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org B4B363858296 Received: by mail-wm1-x331.google.com with SMTP id ay27-20020a05600c1e1b00b003d070f4060bso1597602wmb.2 for ; Thu, 01 Dec 2022 05:55:10 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=QHPqpMFcDcHae9/3me6M7gzbX2E/Ih6ktDpFzDTxJ3w=; b=UEHWUnrAfbvLcofr1dH3oYdpDe35KZdfJ0gPhUi0vsq8a5JlQO3Q01byKSqhfSKGxK CunIpF9hHv+jv82TWAJcwjlYhLKN3oU10oWy2Zc+G/tCRmrwAVnSXq2e6XZ/OUh5S/CK QKx4YEem0/VlVULjn+6bizlUDO4Sgyix+1Z5slixGEJo0H+f1uzutEEe/zNh+IICGLFG BSZCh3AuHxlDKmhJgpBNp8vkdshvyo0UWL5xh6bOGJhdgmmeoR/mVCcAhLLh4u1Vfgqb R/4IBADd/8RSNKl0SJ+e4ZjCy6Jd9p49iNvCcUqzqymhwsMDbDliwfWgi3lVrBXJQPAN C8zg== X-Gm-Message-State: ANoB5pk6E1XFgBbmOZ/1voicxG5RzSWvg1kQhw91Gcsyj25d40Wu2BtF fuYsUdpAnwN1VdAx8UUMt/RYCbYP/bB0AA== X-Google-Smtp-Source: AA0mqf7H15rb/ZLM6hVFI6KzwAjlYKQJky6xkTr/N4EgQtw3S0ANTGTT9uG6DOxixjfI6KgAXjGEvA== X-Received: by 2002:a1c:7401:0:b0:3cf:934b:b7ad with SMTP id p1-20020a1c7401000000b003cf934bb7admr36622405wmc.22.1669902909419; Thu, 01 Dec 2022 05:55:09 -0800 (PST) Received: from localhost.localdomain (static-176-191-105-132.ftth.abo.bbox.fr. [176.191.105.132]) by smtp.gmail.com with ESMTPSA id he9-20020a05600c540900b003b492753826sm5219865wmb.43.2022.12.01.05.55.08 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 01 Dec 2022 05:55:08 -0800 (PST) To: gcc-patches@gcc.gnu.org Cc: Josue Nava Bello Subject: [COMMITTED] ada: Minor updates to gnat/doc configuration Date: Thu, 1 Dec 2022 14:55:05 +0100 Message-Id: <20221201135505.457877-1-poulhies@adacore.com> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 X-Spam-Status: No, score=-13.5 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: =?utf-8?q?Marc_Poulhi=C3=A8s_via_Gcc-patches?= From: =?utf-8?q?Marc_Poulhi=C3=A8s?= Reply-To: =?utf-8?q?Marc_Poulhi=C3=A8s?= Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "Gcc-patches" From: Josue Nava Bello Minor updates to conf.py (comments, indentation) gcc/ada/ * doc/share/conf.py: minor updates Tested on x86_64-pc-linux-gnu, committed on master. --- 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)