[rtems-docs commit] build: Fix indexing so it works on HTML and PDF.

Chris Johns chrisj at rtems.org
Tue Aug 21 03:48:24 UTC 2018


Module:    rtems-docs
Branch:    master
Commit:    5ce8e43506184bd9d8bf072c3f50ad0378f81ee7
Changeset: http://git.rtems.org/rtems-docs/commit/?id=5ce8e43506184bd9d8bf072c3f50ad0378f81ee7

Author:    Chris Johns <chrisj at rtems.org>
Date:      Tue Aug 21 13:41:51 2018 +1000

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(-)

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 %}
+    <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'] %}
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'] %}
-
 <!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]-->
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`



More information about the vc mailing list