Add doxygen source to the generated site (#169)

- added Doxygen source code generation step
- added integration of the result of it into the Dev guide
- added an open_in_blank page option to any links in the links file


Signed-off-by: Hofi <hofione@gmail.com>

Author: HofiOne

.github/workflows/jekyll-gh-pages.yml

@@ -96,6 +96,20 @@ jobs:
           ./_tools/pack debug
           ls -AlR _site/assets/js
 
+          # Generate and add Doxygen source documentation
+          sudo apt-get install doxygen graphviz -y
+
+          OSE_SRC_REPO=https://github.com/syslog-ng/syslog-ng.git
+          OSE_SRC_REPO_BRANCH=develop  # as this is a developer documentation use the latest develop branch instead of the master
+          git clone --branch ${OSE_SRC_REPO_BRANCH} --single-branch ${OSE_SRC_REPO} ./_work
+
+          pushd ./_work
+          # How to override Doxygen options from command line
+          # https://www.doxygen.nl/manual/faq.html#faq_cmdline
+          ( cat ./Doxyfile; echo "OUTPUT_DIRECTORY=../_site/dev-guide/chapter_9/" ) | doxygen -
+          popd
+          rm -Rf ./_work
+
       - name: Upload artifact
         # Automatically uploads an artifact from the './_site' directory by default
         uses: actions/upload-pages-artifact@v3

_data/external_links.yml

@@ -107,6 +107,12 @@ sn-ose-adminguide:
   url: https://syslog-ng.github.io/admin-guide/README
   title: [ "The syslog-ng OSE Administration Guide" ]
 
+sn-ose-source-doc:
+  id: sn-ose-source-doc
+  url: /dev-guide/chapter_9/html/index.html
+  title: [ "syslog-ng OSE source code documentation" ]
+  open_in_blank: true
+
 sn-ose-upgrade:
   id: sn-ose-upgrade
   url: https://syslog-ng.com/blog/upgrading-from-syslog-ng-open-source-to-premium-edition/
@@ -795,7 +801,12 @@ discord-wh-intro:
   id: discord-wh-intro
   url: https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks
   title: [ "Discord: Intro to Webhooks" ]
-  
+
+doxygen-home:
+  id: doxygen-home
+  url: https://www.doxygen.nl/
+  title: [ "Doxygen HomePage" ]
+
 ebpf:
   id: ebpf
   url: https://ebpf.io/

_data/link_aliases.yml

@@ -104,3 +104,6 @@ adm-src-wild:
 
 adm-src-file:
   aliases: [ "/file(?:\\(\\))? source[s]?/" ]
+
+doxygen-home:
+  aliases: [ "/[Dd]oxygen/" ]

_data/navigation.yml

@@ -327,6 +327,9 @@ admin-guide-nav:
         url: /admin-guide/070_Destinations/030_Elasticsearch-http/000_Batch_mode_and_load_balancing
       - title: "elasticsearch-http() destination options"
         url: /admin-guide/070_Destinations/030_Elasticsearch-http/001_Elasticsearch-http_options
+    - title: "elasticsearch-datastream"
+      url: /admin-guide/070_Destinations/035_elasticsearch-datastream/README
+      subnav:
     - title: "file"
       url: /admin-guide/070_Destinations/040_File/README
       subnav:
@@ -1267,6 +1270,9 @@ dev-guide-nav:
       url: /dev-guide/chapter_8/section_4
     - title: "Template Function"
       url: /dev-guide/chapter_8/section_5
+  - title: "Source code documentation"
+    url: /dev-guide/chapter_9/README
+    subnav:
 
 # doc-guide
 doc-guide-nav:

_plugins/generate_tooltips.rb

@@ -54,6 +54,7 @@ def is_modifiable_markdown_part?(part)
       end
 
       def make_tooltip(page, page_links, id, url, match)
+        use_blank = false
         match_parts = match.split(/(?<!\\)\|/)
 
         # If the text has an '|' it means it comes from our special autolink/tooltip [[text|id]] markdown block
@@ -74,6 +75,7 @@ def make_tooltip(page, page_links, id, url, match)
           end
           link_data = page_links[id]
           if link_data != nil
+            use_blank = link_data["open_in_blank"]
             url = link_data["url"]
             url = prefixed_url(url, page.site.config["baseurl"])
           else
@@ -99,7 +101,7 @@ def make_tooltip(page, page_links, id, url, match)
         # NOTE: Now we treat every link that has protocol prefix part as an external one
         #       that allows usage of direct links anywhere if needed (not recommended, plz use external_links.yml instead)
         #       but, at the same time requires e.g. all the really external links to be fully qualified (even in external_links.yml as well)
-        external_url = is_prefixed_url?(url)
+        external_url = is_prefixed_url?(url) || use_blank
         title = save_from_markdownify(title)
         replacement_text = '<a href="' + url + '" class="nav-link content-tooltip"' + (external_url ? ' target="_blank"' : '') + '>' + title + '</a>'
         # puts "replacement_text: " + replacement_text
@@ -345,6 +347,7 @@ def gen_page_link_data(links_dir, link_files_pattern)
           page_id = yaml_content['id']
           page_url = yaml_content['url']
           page_title = yaml_content['title']
+          open_in_blank = yaml_content['open_in_blank']
           chars_to_remove = %{"'}
           page_title = page_title.gsub(/\A[#{Regexp.escape(chars_to_remove)}]+|[#{Regexp.escape(chars_to_remove)}]+\z/, '')
           #puts "page_title: " + page_title
@@ -358,6 +361,7 @@ def gen_page_link_data(links_dir, link_files_pattern)
             "id" => page_id,
             "url" => page_url,
             "title" => [ page_title ],
+            "open_in_blank" => open_in_blank,
           }
 
           # Add the page_link_data object to the ID dictionary
@@ -423,7 +427,7 @@ def JekyllTooltipGen_debug_page_info(page, details = true)
 def JekyllTooltipGen_debug_filter_pages?(page)
   debug_pages = {
     # "doc/README.md" => true,
-}
+  }
   debug_ok = true
   # Comment this line out if not debugging!!!
   # debug_ok = (debug_pages[page.relative_path] != nil && debug_pages[page.relative_path])

_tools/serve

@@ -41,6 +41,10 @@ start_process() {
     # Either use navgen or build once with JEKYLL_BUILD_LINKS manually in a separate run
     # as the output of it must already be presented to be able to serve a valid content
     #
+    if [ "${JEKYLL_BUILD_LINKS}" == "yes" ]; then
+        echo -e "Generating navigation data..."
+        ./_tools/navgen ./doc ./_data/navigation.yml
+    fi
     JEKYLL_BUILD_LINKS='no' bundle exec jekyll serve ${ALL_PARAMS} &
     PROC_PID=$!
 

doc/_dev-guide/chapter_9/README.md

@@ -0,0 +1,6 @@
+---
+title: Source code documentation
+id: dev-source-doc
+---
+
+We have the {{ site.product.short_name }} [[source code documentation|sn-ose-source-doc]] generated via Doxygen.