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
2025-05-31 19:49:42 +08:00 · 2018-08-21 13:41:51 +10:00 · 2018-08-21 13:41:51 +10:00 · 5ce8e43506
commit 5ce8e43506
parent 9bfda06298
30 changed files with 71 additions and 103 deletions
--- a/bsp-howto/genindex.rst
+++ b/bsp-howto/genindex.rst
@ -1,4 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-Index
-=====
--- 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`
--- a/c-user/genindex.rst
+++ b/c-user/genindex.rst
@ -1,4 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-Index
-=====
--- 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`
--- a/common/_templates/layout.html
+++ b/common/_templates/layout.html
@ -1,5 +1,12 @@
 {# Import the theme's layout. #}
 {% extends "!layout.html" %}
-
+{% block sidebartitle %}
+    <a href="https://docs.rtems.org/">RTEMS Documentation Project</a>
+    {{ super() }}
+{% endblock %}
+{% block menu %}
+  {{ super() }}
+  <a class="reference internal" href="genindex.html">Index</a>
+{% endblock %}
 {# Custom CSS overrides #}
-{% set bootswatch_css_custom = ['_static/my-styles.css'] %}
+{% set css_files = ['_static/my-styles.css'] %}
--- 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,
 }


--- 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,
--- 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'] %}
-
 <!DOCTYPE html>
 <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
 <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
--- 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
    )
--- 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`
--- a/develenv/genindex.rst
+++ b/develenv/genindex.rst
@ -1,4 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-Index
-=====
--- 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`
--- a/eclipse/genindex.rst
+++ b/eclipse/genindex.rst
@ -1,4 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-Index
-=====
--- 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`
--- a/filesystem/genindex.rst
+++ b/filesystem/genindex.rst
@ -1,4 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-Index
-=====
--- 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`
--- a/networking/genindex.rst
+++ b/networking/genindex.rst
@ -1,4 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-Index
-=====
--- 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`
--- a/porting/genindex.rst
+++ b/porting/genindex.rst
@ -1,4 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-Index
-=====
--- 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`
--- a/posix-compliance/genindex.rst
+++ b/posix-compliance/genindex.rst
@ -1,4 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-Index
-=====
--- 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`
--- a/posix-users/genindex.rst
+++ b/posix-users/genindex.rst
@ -1,4 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-Index
-=====
--- 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`
--- a/rsb/genindex.rst
+++ b/rsb/genindex.rst
@ -1,4 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-Index
-=====
--- a/rsb/index.rst
+++ b/rsb/index.rst
@ -62,4 +62,4 @@ Table of Contents
 	commands
 	bug-reporting

-        genindex
+* :ref:`genindex`
--- a/shell/genindex.rst
+++ b/shell/genindex.rst
@ -1,4 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-Index
-=====
--- 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`
--- a/user/genindex.rst
+++ b/user/genindex.rst
@ -1,4 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-Index
-=====
--- 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`