From 5ce8e43506184bd9d8bf072c3f50ad0378f81ee7 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Tue, 21 Aug 2018 13:41:51 +1000 Subject: build: Fix indexing so it works on HTML and PDF. - Remove all genindex.rst files, these are generated and should not exist in our source. - Fix the HTML templates so the local specialisation works. - Add a index link to the sidebar for HTML. Note, there is no TOC entry for the index in the PDF output and I cannot figure out how to add one. Closes #3503 --- bsp-howto/genindex.rst | 4 -- bsp-howto/index.rst | 2 +- c-user/genindex.rst | 4 -- c-user/index.rst | 2 +- common/_templates/layout.html | 11 ++++- common/conf.py | 6 ++- common/rtemsstyle.sty | 4 -- common/sphinx_rtd_theme_rtems/layout.html | 3 -- common/waf.py | 76 ++++++++++++++++++------------- cpu-supplement/index.rst | 2 + develenv/genindex.rst | 4 -- develenv/index.rst | 2 +- eclipse/genindex.rst | 4 -- eclipse/index.rst | 2 +- filesystem/genindex.rst | 4 -- filesystem/index.rst | 2 +- networking/genindex.rst | 4 -- networking/index.rst | 2 +- porting/genindex.rst | 4 -- porting/index.rst | 2 +- posix-compliance/genindex.rst | 4 -- posix-compliance/index.rst | 2 +- posix-users/genindex.rst | 4 -- posix-users/index.rst | 2 +- rsb/genindex.rst | 4 -- rsb/index.rst | 2 +- shell/genindex.rst | 4 -- shell/index.rst | 2 +- user/genindex.rst | 4 -- user/index.rst | 2 +- 30 files changed, 71 insertions(+), 103 deletions(-) delete mode 100644 bsp-howto/genindex.rst delete mode 100644 c-user/genindex.rst delete mode 100644 develenv/genindex.rst delete mode 100644 eclipse/genindex.rst delete mode 100644 filesystem/genindex.rst delete mode 100644 networking/genindex.rst delete mode 100644 porting/genindex.rst delete mode 100644 posix-compliance/genindex.rst delete mode 100644 posix-users/genindex.rst delete mode 100644 rsb/genindex.rst delete mode 100644 shell/genindex.rst delete mode 100644 user/genindex.rst diff --git a/bsp-howto/genindex.rst b/bsp-howto/genindex.rst deleted file mode 100644 index 07b4393..0000000 --- a/bsp-howto/genindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Index -===== diff --git a/bsp-howto/index.rst b/bsp-howto/index.rst index 290ff1c..44df735 100644 --- a/bsp-howto/index.rst +++ b/bsp-howto/index.rst @@ -61,4 +61,4 @@ to the Community Project hosted at http://www.rtems.org/. ide_controller command - genindex +* :ref:`genindex` diff --git a/c-user/genindex.rst b/c-user/genindex.rst deleted file mode 100644 index 07b4393..0000000 --- a/c-user/genindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Index -===== diff --git a/c-user/index.rst b/c-user/index.rst index d125c28..0c1906e 100644 --- a/c-user/index.rst +++ b/c-user/index.rst @@ -83,4 +83,4 @@ to the Community Project hosted at http://www.rtems.org/. glossary zreferences - genindex +* :ref:`genindex` diff --git a/common/_templates/layout.html b/common/_templates/layout.html index 7f64789..7a66d8a 100644 --- a/common/_templates/layout.html +++ b/common/_templates/layout.html @@ -1,5 +1,12 @@ {# Import the theme's layout. #} {% extends "!layout.html" %} - +{% block sidebartitle %} + RTEMS Documentation Project + {{ super() }} +{% endblock %} +{% block menu %} + {{ super() }} + Index +{% endblock %} {# Custom CSS overrides #} -{% set bootswatch_css_custom = ['_static/my-styles.css'] %} +{% set css_files = ['_static/my-styles.css'] %} diff --git a/common/conf.py b/common/conf.py index 388ac0f..3c8ae76 100644 --- a/common/conf.py +++ b/common/conf.py @@ -34,7 +34,7 @@ extensions = [ ] # Add any paths that contain templates here, relative to this directory. -templates_path = ['build/_templates'] +#templates_path = ['build/_templates'] # The suffix of source filenames. source_suffix = '.rst' @@ -202,7 +202,9 @@ latex_elements = { 'preamble': r''' \newcommand{\rtemscopyright}{%s} \usepackage{rtemsstyle} -''' % (copyright) +''' % (copyright), + 'printindex': r'\footnotesize\raggedright\printindex', + 'parsedliteralwraps': True, } diff --git a/common/rtemsstyle.sty b/common/rtemsstyle.sty index 96313f1..fe82b52 100644 --- a/common/rtemsstyle.sty +++ b/common/rtemsstyle.sty @@ -10,10 +10,6 @@ \renewenvironment{tabulary}{\underscoresplit\oldtabulary}{\endoldtabulary\endunderscoresplit} -\let\oldprintindex\printindex - -\renewenvironment{printindex}{\underscoresplit\oldprintindex} - \usepackage{minted} \fvset{ breaklines=true, diff --git a/common/sphinx_rtd_theme_rtems/layout.html b/common/sphinx_rtd_theme_rtems/layout.html index 86927c6..44978c9 100644 --- a/common/sphinx_rtd_theme_rtems/layout.html +++ b/common/sphinx_rtd_theme_rtems/layout.html @@ -7,9 +7,6 @@ {%- set titlesuffix = "" %} {%- endif %} -{# Custom CSS overrides #} -{% set extra_css_files = ['_static/my-styles.css'] %} - diff --git a/common/waf.py b/common/waf.py index ae287cb..1ef7172 100644 --- a/common/waf.py +++ b/common/waf.py @@ -1,4 +1,16 @@ -import sys, os, re +# +# RTEMS Documentation Project +# +# Waf build support. +# + + +from __future__ import print_function + +import os +import re +import sys + from waflib.Build import BuildContext import latex @@ -24,10 +36,14 @@ def build_date(): def version_cmdline(ctx): return '-Drelease="%s" -Dversion="%s"' % (ctx.env.VERSION, ctx.env.VERSION) -def sphinx_cmdline(ctx, build_type, conf_dir, doctrees, source_dir, output_dir): - rule = "${BIN_SPHINX_BUILD} %s -b %s -c %s %s -d %s %s %s ${SRC}" % \ +def sphinx_cmdline(ctx, build_type, conf_dir, doctrees, + source_dir, output_dir, configs = []): + cfgs = '' + for c in configs: + cfgs += ' -D %s=%s' % (c, configs[c]) + rule = "${BIN_SPHINX_BUILD} %s -b %s -c %s %s -d %s %s %s %s ${SRC}" % \ (sphinx_verbose(ctx), build_type, conf_dir, version_cmdline(ctx), - doctrees, source_dir, output_dir) + doctrees, cfgs, source_dir, output_dir) return rule def cmd_spell(ctx): @@ -140,43 +156,35 @@ def pdf_resources(ctx, buildtype): fnode = ctx.path.get_bld().make_node(buildtype) fnode.mkdir() local_packages = latex.local_packages() + targets = [] if local_packages is not None: srcs = [os.path.join(base, p) for p in local_packages] - ctx( - features = "subst", + targets += [fnode.make_node(p) for p in local_packages] + ctx(features = "subst", is_copy = True, source = srcs, - target = [fnode.make_node(p) for p in local_packages] - ) - ctx( - features = "subst", + target = targets) + targets += [fnode.make_node('rtemsextrafonts.sty')] + ctx(features = "subst", is_copy = True, source = os.path.join(base, ctx.env.RTEMSEXTRAFONTS), - target = fnode.make_node('rtemsextrafonts.sty') - ) + target = fnode.make_node('rtemsextrafonts.sty')) + return targets def html_resources(ctx, buildtype): + extra_source = [] for dir_name in ["_static", "_templates"]: files = ctx.path.parent.find_node("common").ant_glob("%s/*" % dir_name) fnode = ctx.path.get_bld().make_node(os.path.join(buildtype, dir_name)) + targets = [fnode.make_node(x.name) for x in files] + extra_source += targets fnode.mkdir() # dirs - ctx( - features = "subst", + ctx(features = "subst", is_copy = True, source = files, - target = [fnode.make_node(x.name) for x in files] - ) - - # copy images -# ctx.path.get_bld().make_node("images").mkdir() -# files = ctx.path.parent.ant_glob("images/**") -# ctx( -# features = "subst", -# is_copy = True, -# source = files, -# target = [x.srcpath().replace("../", "") for x in files] -# ) - + target = targets) + ctx.add_group() + return extra_source def check_sphinx_extension(ctx, extension): def run_sphinx(bld): @@ -196,7 +204,6 @@ def check_sphinx_extension(ctx, extension): ctx.fatal('The configuration failed') ctx.end_msg('found') - def cmd_configure(ctx): check_sphinx = not ctx.env.BIN_SPHINX_BUILD if check_sphinx: @@ -256,12 +263,13 @@ def cmd_configure(ctx): def doc_pdf(ctx, source_dir, conf_dir, extra_source): buildtype = 'latex' build_dir, output_node, output_dir, doctrees = build_dir_setup(ctx, buildtype) - pdf_resources(ctx, buildtype) + resources = pdf_resources(ctx, buildtype) rule = sphinx_cmdline(ctx, buildtype, conf_dir, doctrees, source_dir, output_dir) ctx( rule = rule, cwd = ctx.path, source = ctx.path.ant_glob('**/*.rst') + extra_source, + depends_on = extra_source, target = ctx.path.find_or_declare("%s/%s.tex" % (buildtype, ctx.path.name)) ) @@ -306,12 +314,13 @@ def doc_singlehtml(ctx, source_dir, conf_dir, extra_source): buildtype = 'singlehtml' build_dir, output_node, output_dir, doctrees = build_dir_setup(ctx, buildtype) - html_resources(ctx, buildtype) + resource = html_resources(ctx, buildtype) rule = sphinx_cmdline(ctx, buildtype, conf_dir, doctrees, source_dir, output_dir) ctx( rule = rule, cwd = ctx.path, source = ctx.path.ant_glob('**/*.rst') + extra_source, + depends_on = resources, target = ctx.path.find_or_declare("%s/index.html" % (buildtype)), install_path = None ) @@ -326,12 +335,15 @@ def doc_singlehtml(ctx, source_dir, conf_dir, extra_source): def doc_html(ctx, source_dir, conf_dir, extra_source): buildtype = 'html' build_dir, output_node, output_dir, doctrees = build_dir_setup(ctx, buildtype) - html_resources(ctx, buildtype) - rule = sphinx_cmdline(ctx, buildtype, conf_dir, doctrees, source_dir, output_dir) + resources = html_resources(ctx, buildtype) + templates = os.path.join(str(ctx.path.get_bld()), buildtype, '_templates') + configs = { 'templates_path': templates } + rule = sphinx_cmdline(ctx, buildtype, conf_dir, doctrees, source_dir, output_dir, configs) ctx( rule = rule, cwd = ctx.path, source = ctx.path.ant_glob('**/*.rst') + extra_source, + depends_on = resources, target = ctx.path.find_or_declare('%s/index.html' % buildtype), install_path = None ) diff --git a/cpu-supplement/index.rst b/cpu-supplement/index.rst index f218126..1fe8bd2 100644 --- a/cpu-supplement/index.rst +++ b/cpu-supplement/index.rst @@ -61,3 +61,5 @@ to the Community Project hosted at http://www.rtems.org/. sparc sparc64 zreferences + +* :ref:`genindex` diff --git a/develenv/genindex.rst b/develenv/genindex.rst deleted file mode 100644 index 07b4393..0000000 --- a/develenv/genindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Index -===== diff --git a/develenv/index.rst b/develenv/index.rst index 0c30eb6..fb2dbcf 100644 --- a/develenv/index.rst +++ b/develenv/index.rst @@ -47,4 +47,4 @@ to the Community Project hosted at http://www.rtems.org/. utilities command - genindex +* :ref:`genindex` diff --git a/eclipse/genindex.rst b/eclipse/genindex.rst deleted file mode 100644 index 07b4393..0000000 --- a/eclipse/genindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Index -===== diff --git a/eclipse/index.rst b/eclipse/index.rst index 2865563..572c7d9 100644 --- a/eclipse/index.rst +++ b/eclipse/index.rst @@ -50,4 +50,4 @@ to the Community Project hosted at http://www.rtems.org/. glossary - genindex +* :ref:`genindex` diff --git a/filesystem/genindex.rst b/filesystem/genindex.rst deleted file mode 100644 index 07b4393..0000000 --- a/filesystem/genindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Index -===== diff --git a/filesystem/index.rst b/filesystem/index.rst index 98b024c..8719e0a 100644 --- a/filesystem/index.rst +++ b/filesystem/index.rst @@ -52,4 +52,4 @@ to the Community Project hosted at http://www.rtems.org/. trivial_ftp command_and_variable - genindex +* :ref:`genindex` diff --git a/networking/genindex.rst b/networking/genindex.rst deleted file mode 100644 index 07b4393..0000000 --- a/networking/genindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Index -===== diff --git a/networking/index.rst b/networking/index.rst index 99a7d84..10b12d3 100644 --- a/networking/index.rst +++ b/networking/index.rst @@ -52,4 +52,4 @@ to the Community Project hosted at http://www.rtems.org/. dec_21140 command - genindex +* :ref:`genindex` diff --git a/porting/genindex.rst b/porting/genindex.rst deleted file mode 100644 index 07b4393..0000000 --- a/porting/genindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Index -===== diff --git a/porting/index.rst b/porting/index.rst index 88fad65..e838458 100644 --- a/porting/index.rst +++ b/porting/index.rst @@ -54,4 +54,4 @@ to the Community Project hosted at http://www.rtems.org/. miscellanous command - genindex +* :ref:`genindex` diff --git a/posix-compliance/genindex.rst b/posix-compliance/genindex.rst deleted file mode 100644 index 07b4393..0000000 --- a/posix-compliance/genindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Index -===== diff --git a/posix-compliance/index.rst b/posix-compliance/index.rst index c7caee2..e0fad90 100644 --- a/posix-compliance/index.rst +++ b/posix-compliance/index.rst @@ -48,4 +48,4 @@ to the Community Project hosted at http://www.rtems.org/. glossary zreferences - genindex +* :ref:`genindex` diff --git a/posix-users/genindex.rst b/posix-users/genindex.rst deleted file mode 100644 index 07b4393..0000000 --- a/posix-users/genindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Index -===== diff --git a/posix-users/index.rst b/posix-users/index.rst index ceace7a..017384a 100644 --- a/posix-users/index.rst +++ b/posix-users/index.rst @@ -67,4 +67,4 @@ to the Community Project hosted at http://www.rtems.org/. status_of_implementation command - genindex +* :ref:`genindex` diff --git a/rsb/genindex.rst b/rsb/genindex.rst deleted file mode 100644 index 07b4393..0000000 --- a/rsb/genindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Index -===== diff --git a/rsb/index.rst b/rsb/index.rst index 3f46b9f..7b64945 100644 --- a/rsb/index.rst +++ b/rsb/index.rst @@ -62,4 +62,4 @@ Table of Contents commands bug-reporting - genindex +* :ref:`genindex` diff --git a/shell/genindex.rst b/shell/genindex.rst deleted file mode 100644 index 07b4393..0000000 --- a/shell/genindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Index -===== diff --git a/shell/index.rst b/shell/index.rst index c56c384..99279c3 100644 --- a/shell/index.rst +++ b/shell/index.rst @@ -55,4 +55,4 @@ to the Community Project hosted at http://www.rtems.org/. function_and_variable concept - genindex +* :ref:`genindex` diff --git a/user/genindex.rst b/user/genindex.rst deleted file mode 100644 index 07b4393..0000000 --- a/user/genindex.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Index -===== diff --git a/user/index.rst b/user/index.rst index 09f755b..750c4dd 100644 --- a/user/index.rst +++ b/user/index.rst @@ -59,4 +59,4 @@ to the Community Project hosted at http://www.rtems.org/. glossary/index - genindex +* :ref:`genindex` -- cgit v1.2.3