[gegl] docs: add navigation to website

[Øyvind "pippin" Kolås <ok src gnome org>]

commit 57495ab7b1a0e3558b65793d0e41e5e02536607c
Author: John <jtm home gmail com>
Date:   Sat Feb 20 22:08:24 2021 +0000

    docs: add navigation to website

 docs/meson.build                                   | 138 +++++++++++++--------
 docs/website/meson.build                           |  89 ++++++-------
 docs/website/website-content.adoc                  |  13 ++
 docs/website/{source.adoc => website-listing.adoc} |  12 +-
 4 files changed, 149 insertions(+), 103 deletions(-)
---
diff --git a/docs/meson.build b/docs/meson.build
index 0968e33d5..1c14d1d4d 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -6,16 +6,6 @@ if not build_docs
   subdir_done()
 endif
 
-# website
-doc_env = [
-  'GEGL_SWAP=' + project_build_root / 'RAM',
-  'GEGL_PATH=' + gegl_operations_build_dir,
-  'BABL_TOLERANCE=0.0',
-]
-if is_variable('babl_path')
-  doc_env += 'BABL_PATH=' + babl_path
-endif
-
 # images
 images = files(
   'images' / 'GEGL.png',
@@ -24,54 +14,18 @@ images = files(
 )
 
 # stylesheets
+gegl_css = files('gegl.css')
 stylesheets = files(
   'devhelp.css'
 )
 
-# stand-alone asciidoc files - not part of website
-asciidoc_files = files(
-  'NEWS.adoc',
-  'contribute.adoc',
-  'editor.adoc',
-  'journal.adoc',
+# website main page - one file only
+website_index = files(
+  'index.adoc'
 )
 
-_tgt = []
-foreach _file: asciidoc_files
-  _tgt += custom_target(
-    '@0@.html'.format(_file).underscorify(),
-    output: '@BASENAME@.html',
-    input: _file,
-    command: [
-      asciidoc,
-      '--unsafe',
-      '-o', '@OUTPUT@',
-      '-a', 'stylesheet=@0@'.format(
-        project_source_root / 'docs' / 'gegl.css'
-      ),
-      '-a', 'quirks!',
-      '@INPUT@',
-    ],
-    build_by_default : true,
-  )
-endforeach
-news_html = _tgt[0]
-
-# website asciidoc files
-if can_run_host_binaries
-  gegl_usage = custom_target(
-    'gegl_usage_txt',
-    output: 'gegl-usage.txt',
-    command: [
-      find_program('gegl-usage.py'),
-      '--output', '@OUTPUT@',
-      '--gegl-exe', gegl_bin,
-    ]
-  )
-endif
-
-website_asciidoc_files = files(
-  'index.adoc',
+# website content
+website_content = files(
   'abyss_policy.adoc',
   'commandline.adoc',
   'copyright.adoc',
@@ -85,7 +39,7 @@ website_asciidoc_files = files(
   'release-notes.adoc',
   'source-overview.adoc',
 )
-website_asciidoc_files += [
+website_content += [
   configure_file(
     input : 'build.adoc.in',
     output: '@BASENAME@',
@@ -93,6 +47,61 @@ website_asciidoc_files += [
   ),
 ]
 
+# Website source listings
+src_gegl_operation = project_source_root / 'gegl' / 'operation'
+website_listing_files = files(
+  src_gegl_operation / 'gegl-operation.h',
+  src_gegl_operation / 'gegl-operation-composer.h',
+  src_gegl_operation / 'gegl-operation-area-filter.h',
+  src_gegl_operation / 'gegl-operation-filter.h',
+  src_gegl_operation / 'gegl-operation-meta.h',
+  src_gegl_operation / 'gegl-operation-point-composer.h',
+  src_gegl_operation / 'gegl-operation-temporal.h',
+  src_gegl_operation / 'gegl-operation-point-filter.h',
+  src_gegl_operation / 'gegl-operation-point-render.h',
+  src_gegl_operation / 'gegl-operation-sink.h',
+  src_gegl_operation / 'gegl-operation-source.h',
+  project_source_root / 'operations' / 'common' /
+   'brightness-contrast.c',
+)
+
+# Standalone content
+standalone_content = files(
+  'NEWS.adoc',
+  'contribute.adoc',
+  'editor.adoc',
+  'journal.adoc',
+)
+
+website_index_deps = []
+website_content_deps = []
+website_listing_deps = []
+standalone_content_deps = []
+
+# Documentation build environment
+doc_env = [
+  'GEGL_SWAP=' + project_build_root / 'RAM',
+  'GEGL_PATH=' + gegl_operations_build_dir,
+  'BABL_TOLERANCE=0.0',
+]
+if is_variable('babl_path')
+  doc_env += 'BABL_PATH=' + babl_path
+endif
+
+# website include files
+if can_run_host_binaries
+  gegl_usage = custom_target(
+    'gegl_usage_txt',
+    output: 'gegl-usage.txt',
+    command: [
+      find_program('gegl-usage.py'),
+      '--output', '@OUTPUT@',
+      '--gegl-exe', gegl_bin,
+    ]
+  )
+  website_content_deps += gegl_usage
+endif
+
 # Inheritance diagram
 inheritance_txt = custom_target(
   'inheritance_txt',
@@ -106,5 +115,28 @@ inheritance_txt = custom_target(
   ],
 )
 
+# build stand-alone asciidoc files - not part of website
+_tgt = []
+foreach _file: standalone_content
+  _tgt += custom_target(
+    '@0@.html'.format(_file).underscorify(),
+    output: '@BASENAME@.html',
+    input: _file,
+    command: [
+      asciidoc,
+      '--unsafe',
+      '-o', '@OUTPUT@',
+      '-a', 'stylesheet=@0@'.format(
+        meson.current_source_dir() / 'gegl.css'
+      ),
+      '-a', 'quirks!',
+      '@INPUT@',
+    ],
+    depends: standalone_content_deps,
+    build_by_default : true,
+  )
+endforeach
+news_html = _tgt[0]
+
 
 subdir('website')
diff --git a/docs/website/meson.build b/docs/website/meson.build
index d800579b3..7359281d1 100644
--- a/docs/website/meson.build
+++ b/docs/website/meson.build
@@ -1,5 +1,10 @@
 
+subdir('images')
+subdir('operations')
+
 # stylesheets
+gegl_css = project_source_root / 'docs' / 'gegl.css'
+
 foreach _file : stylesheets
   configure_file(
     input : _file,
@@ -8,7 +13,8 @@ foreach _file : stylesheets
   )
 endforeach
 
-# HTML files
+# generate website
+# website - class hierarchy reference
 if env.found() and can_run_host_binaries
   custom_target(
     'class_hierarchy_html',
@@ -26,10 +32,9 @@ else
   warning('Cannot create class reference in this environment')
 endif
 
-# generate website html files
-_tgt = []
-foreach _file: website_asciidoc_files
-  _tgt += custom_target(
+# website content
+foreach _file: website_content
+  custom_target(
     '@0@.html'.format(_file).underscorify(),
     output: '@BASENAME@.html',
     input: _file,
@@ -37,63 +42,59 @@ foreach _file: website_asciidoc_files
       asciidoc,
       '--unsafe',
       '-o', '@OUTPUT@',
-      '-a', 'gegl_usage=@0@'.format(gegl_usage.full_path()),
-      '-a', 'stylesheet=@0@'.format(
-        project_source_root / 'docs' / 'gegl.css'
-      ),
+      '-a', 'stylesheet=@0@'.format(gegl_css),
       '-a', 'highlight=@0@'.format(source_highlight.found()),
+      '-a', 'build_root=@0@'.format(project_build_root),
       '-a', 'source_root=@0@'.format(project_source_root),
+      '-a', 'content=@0@'.format('@INPUT@'),
+      '-a', 'name=@0@'.format('@BASENAME@'),
       '-a', 'quirks!',
-      '@INPUT@',
+      files('website-content.adoc'),
     ],
+    depends: website_content_deps,
     build_by_default : true,
-    depends: gegl_usage,
   )
 endforeach
-index_html = _tgt[0]
-
-# Source files
-src_gegl = project_source_root / 'gegl'
-src_gegl_operation =  src_gegl / 'operation'
-source_files = {
-  'gegl-operation.h' : src_gegl_operation,
-  'gegl-operation-composer.h' : src_gegl_operation,
-  'gegl-operation-area-filter.h' : src_gegl_operation,
-  'gegl-operation-filter.h' : src_gegl_operation,
-  'gegl-operation-meta.h' : src_gegl_operation,
-  'gegl-operation-point-composer.h' : src_gegl_operation,
-  'gegl-operation-temporal.h' : src_gegl_operation,
-  'gegl-operation-point-filter.h' : src_gegl_operation,
-  'gegl-operation-point-render.h' : src_gegl_operation,
-  'gegl-operation-sink.h' : src_gegl_operation,
-  'gegl-operation-source.h' : src_gegl_operation,
-  'brightness-contrast.c' :
-    project_source_root / 'operations' / 'common',
-}
 
-# generate operation api website source files
-foreach _file, _path : source_files
+# website source listings
+foreach _file : website_listing_files
   custom_target(
     '@0@.html'.format(_file).underscorify(),
-    input: 'source.adoc',
-    output: '@0@.html'.format(_file),
+    input: _file,
+    output: '@PLAINNAME@.html',
     command: [
       asciidoc,
       '--unsafe',
       '-o', '@OUTPUT@',
-      '-a', 'stylesheet=@0@'.format(
-        project_source_root / 'docs' / 'gegl.css'
-      ),
+      '-a', 'stylesheet=@0@'.format(gegl_css),
       '-a', 'highlight=@0@'.format(source_highlight.found()),
-      '-a', 'name=@0@'.format(_file),
-      '-a', 'full_path=@0@'.format(_path / _file),
+      '-a', 'build_root=@0@'.format(project_build_root),
+      '-a', 'source_root=@0@'.format(project_source_root),
+      '-a', 'content=@0@'.format('@INPUT@'),
+      '-a', 'name=@0@'.format('@PLAINNAME@'),
+      '-a', 'parent_link=operation-api.html',
+      '-a', 'parent=GEGL Operation API',
       '-a', 'quirks!',
-      '@INPUT@',
+      files('website-listing.adoc'),
     ],
+    depends: website_listing_deps,
     build_by_default: true,
   )
 endforeach
 
-
-subdir('images')
-subdir('operations')
+# website index
+index_html = custom_target(
+  'index_html',
+  output: 'index.html',
+  input: website_index,
+  command: [
+    asciidoc,
+    '--unsafe',
+    '-o', '@OUTPUT@',
+    '-a', 'stylesheet=@0@'.format(gegl_css),
+    '-a', 'quirks!',
+    '@INPUT@',
+  ],
+  depends: website_index_deps,
+  build_by_default : true,
+)
diff --git a/docs/website/website-content.adoc b/docs/website/website-content.adoc
new file mode 100644
index 000000000..d2f7e977b
--- /dev/null
+++ b/docs/website/website-content.adoc
@@ -0,0 +1,13 @@
+{name}
+======
+
+[[top]]
+image::images/GEGL-250.png[link="index.html"]
+
+
+include::{build_root}/{content}[]
+
+
+{empty} +
+xref:top[top]
+[[end]]
diff --git a/docs/website/source.adoc b/docs/website/website-listing.adoc
similarity index 72%
rename from docs/website/source.adoc
rename to docs/website/website-listing.adoc
index 956ab1efd..31773633f 100644
--- a/docs/website/source.adoc
+++ b/docs/website/website-listing.adoc
@@ -1,19 +1,19 @@
-Operation API
-=============
+{name}
+======
 
 [[top]]
 image::images/GEGL-250.png[link="index.html"]
 
 
-GEGL Operation API
-------------------
+link:{parent_link}[{parent}]
+----------------------------
 
 // Use source highlighting if available
 ifeval::["{highlight}" == "true"]
 [source, c]
 .{name}
 -----
-include::{full_path}[]
+include::{content}[]
 -----
 endif::[]
 
@@ -21,7 +21,7 @@ endif::[]
 ifeval::["{highlight}" != "true"]
 .{name}
 .....
-include::{full_path}[]
+include::{content}[][]
 .....
 endif::[]