Merge pull request #352 from yakatz/update_docs

Customize YARD generation

.github/workflows/pages.yml

@@ -35,7 +35,7 @@ jobs:
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: doc
+          path: build_docs
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4

.gitignore

@@ -8,6 +8,6 @@ vendor/
 .yardoc
 packer_cache/
 *.box
-doc/
+build_docs/
 database/
 hugo/public

.yardopts

@@ -1,2 +1,7 @@
+--output-dir ./build_docs
+--template-path doc/templates/
+--template facterdb
 --title 'FacterDB Documentation'
---files CHANGELOG.md,database/*
+--files README.md,CHANGELOG.md,database/*
+--asset images/
+--main doc/main.md

README.md

@@ -57,6 +57,11 @@ require 'facterdb'
 FacterDB::get_facts('osfamily=Debian')
 ```
 
+## Included Factsets
+
+Starting with version 1.28.0 (May 2024), check [RubyDoc](https://www.rubydoc.info/gems/facterdb/) for Factsets included in each released gem.
+Check the [Voxpupuli website](https://voxpupuli.org/facterdb/) for Factsets included in the `master` branch.
+
 ## Add new Operating System support
 
 There is `Vagrantfile` to automagically populate `facts` for all supported operating systems by spawning a new VM and launches a provisioning scripts.

doc/main.md

@@ -0,0 +1,32 @@
+facterdb
+========
+
+[![License](https://img.shields.io/github/license/voxpupuli/facterdb.svg)](https://github.com/voxpupuli/facterdb/blob/master/LICENSE)
+[![Test](https://github.com/voxpupuli/facterdb/actions/workflows/test.yml/badge.svg)](https://github.com/voxpupuli/facterdb/actions/workflows/test.yml)
+[![Release](https://github.com/voxpupuli/facterdb/actions/workflows/release.yml/badge.svg)](https://github.com/voxpupuli/facterdb/actions/workflows/release.yml)
+[![RubyGem Version](https://img.shields.io/gem/v/facterdb.svg)](https://rubygems.org/gems/facterdb)
+[![RubyGem Downloads](https://img.shields.io/gem/dt/facterdb.svg)](https://rubygems.org/gems/facterdb)
+[![Donated by Camptocamp](https://img.shields.io/badge/donated%20by-camptocamp-fb7047.svg)](#transfer-notice)
+
+A Gem that contains a lot of facts for a lot of Operating Systems.
+
+![FacterDB](images/facterdb.png)
+
+## GEM Documentation
+
+Start with the {file:README.md}.
+
+## Included Factsets
+
+There may be Factsets available for any combination of `Operating System`, `Architecture` (i.e. `i386`, `x86_64`, `arm64`), and `Facter Version`.
+
+The list of factsets is available in several different formats:
+
+- {file:database/table.md Table of Operating Systems and Facter Versions} - this is the table that was formerly available in the README.
+- {file:database/list_arch_os_facter.md List: Grouped by Architecture -> Operating System}
+- {file:database/list_facter_os_arch.md List: Grouped by Facter Version -> Operating System}
+- {file:database/list_os_arch_facter.md List: Grouped by Operating System -> Architecture}
+- {file:database/list_os_facter_arch.md List: Grouped by Operating System -> Facter Version}
+
+Starting with version 1.28.0 (May 2024), check [RubyDoc](https://www.rubydoc.info/gems/facterdb/) for Factsets included in each released gem.
+

doc/templates/facterdb/class/html/setup.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+include T('default/class/html')

doc/templates/facterdb/constant/html/setup.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+include T('default/constant/html')

doc/templates/facterdb/docstring/html/setup.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+include T('default/docstring/html')

doc/templates/facterdb/fulldoc/html/css/vox.css

@@ -0,0 +1,39 @@
+.fixed_header .logo {
+  background-color: #0d6efd;
+  color: #fff;
+  padding: .75em;
+}
+
+.fixed_header .logo a {
+  width: 100%;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+}
+
+.fixed_header .logo a:link,
+.fixed_header .logo a:visited
+{
+  font-size: 1.4em;
+  color: #fff;
+}
+
+.fixed_header .logo img {
+  max-width: 32px;
+  display: inline-block;
+  vertical-align:middle;
+}
+
+.content {
+  display: flex;
+  flex-direction: column;
+}
+
+#full_list {
+  margin-top: 0;
+}
+
+.fixed_header {
+  height: auto;
+  position: static;
+}

doc/templates/facterdb/fulldoc/html/full_list.erb

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta charset="<%= charset %>" />
+    <% stylesheets_full_list.each do |stylesheet| %>
+      <link rel="stylesheet" href="<%= mtime_url(stylesheet) %>" type="text/css" media="screen" />
+    <% end %>
+
+    <% javascripts_full_list.each do |javascript| %>
+      <script type="text/javascript" charset="utf-8" src="<%= mtime_url(javascript) %>"></script>
+    <% end %>
+
+    <title><%= @list_title %></title>
+    <base id="base_target" target="_parent" />
+  </head>
+  <body>
+    <div id="content">
+      <div class="fixed_header">
+        <div class="logo">
+          <a href="https://voxpupuli.org/" target="_blank">
+            <img src="images/8bit-vox.png"> Vox Pupuli
+          </a>
+        </div>
+        <h1><%= @list_title %></h1>
+        <div id="full_list_nav">
+          <% menu_lists.each do |list| %>
+            <span><a target="_self" href="<%= url_for_list list[:type] %>">
+              <%= list[:title] %>
+            </a></span>
+          <% end %>
+        </div>
+
+        <div id="search">Search: <input type="text" /></div>
+      </div>
+
+      <div>
+        <ul id="full_list" class="<%= @list_class || @list_type %>">
+          <%= erb "full_list_#{@list_type}" %>
+        </ul>
+      </div>
+    </div>
+  </body>
+</html>
+

doc/templates/facterdb/fulldoc/html/setup.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+include T('default/fulldoc/html')
+
+def stylesheets_full_list
+  # Load the existing stylesheets while appending the custom one
+  super + %w[css/vox.css]
+end

doc/templates/facterdb/layout/html/setup.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+include T('default/layout/html')
+
+def layout
+  @nav_url = url_for_list((defined?(@file) && @file) ? 'file' : 'class')
+
+  @path =
+    if !object || object.is_a?(String)
+      nil
+    elsif defined?(@file) && @file
+      @file.path
+    elsif !object.is_a?(YARD::CodeObjects::NamespaceObject)
+      object.parent.path
+    else
+      object.path
+    end
+
+  erb(:layout)
+end

doc/templates/facterdb/method/html/setup.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+include T('default/method/html')

doc/templates/facterdb/method_details/html/setup.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+include T('default/method_details/html')

doc/templates/facterdb/module/html/setup.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+include T('default/module/html')

doc/templates/facterdb/onefile/html/setup.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+include T('default/onefile/html')

doc/templates/facterdb/root/html/setup.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+include T('default/root/html')

doc/templates/facterdb/tags/html/setup.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+include T('default/tags/html')