7991 fontcustom

doc/sphinx-guides/source/_static/fontcustom.css

@@ -4,20 +4,20 @@
 
 @font-face {
   font-family: "fontcustom";
-  src: url("./fontcustom/fontcustom_fb6bd74e6004cae7db6ffae62177daaf.eot");
-  src: url("./fontcustom/fontcustom_fb6bd74e6004cae7db6ffae62177daaf.eot?#iefix") format("embedded-opentype"),
-       url("./fontcustom/fontcustom_fb6bd74e6004cae7db6ffae62177daaf.woff2") format("woff2"),
-       url("./fontcustom/fontcustom_fb6bd74e6004cae7db6ffae62177daaf.woff") format("woff"),
-       url("./fontcustom/fontcustom_fb6bd74e6004cae7db6ffae62177daaf.ttf") format("truetype"),
-       url("./fontcustom/fontcustom_fb6bd74e6004cae7db6ffae62177daaf.svg#fontcustom") format("svg");
+  src: url("fontcustom/fontcustom_0f2e3abd7943864d8b51d195be0f5883.eot");
+  src: url("fontcustom/fontcustom_0f2e3abd7943864d8b51d195be0f5883.eot?#iefix") format("embedded-opentype"),
+       url("fontcustom/fontcustom_0f2e3abd7943864d8b51d195be0f5883.woff2") format("woff2"),
+       url("fontcustom/fontcustom_0f2e3abd7943864d8b51d195be0f5883.woff") format("woff"),
+       url("fontcustom/fontcustom_0f2e3abd7943864d8b51d195be0f5883.ttf") format("truetype"),
+       url("fontcustom/fontcustom_0f2e3abd7943864d8b51d195be0f5883.svg#fontcustom") format("svg");
   font-weight: normal;
   font-style: normal;
 }
 
 @media screen and (-webkit-min-device-pixel-ratio:0) {
   @font-face {
     font-family: "fontcustom";
-    src: url("./fontcustom/fontcustom_fb6bd74e6004cae7db6ffae62177daaf.svg#fontcustom") format("svg");
+    src: url("fontcustom/fontcustom_0f2e3abd7943864d8b51d195be0f5883.svg#fontcustom") format("svg");
   }
 }
 
@@ -53,18 +53,18 @@
   font-smoothing: antialiased;
 }
 
-.icon-astro:before { content: "\f104"; }
-.icon-audio:before { content: "\f105"; }
-.icon-code:before { content: "\f10b"; }
-.icon-dataset:before { content: "\f102"; }
-.icon-dataverse:before { content: "\f100"; }
-.icon-document:before { content: "\f106"; }
-.icon-file:before { content: "\f10a"; }
-.icon-geodata:before { content: "\f107"; }
-.icon-image:before { content: "\f103"; }
-.icon-network:before { content: "\f10c"; }
-.icon-other:before { content: "\f10d"; }
-.icon-package:before { content: "\f10f"; }
-.icon-tabular:before { content: "\f108"; }
-.icon-unlock:before { content: "\f10e"; }
-.icon-video:before { content: "\f109"; }
+.icon-astro:before { content: "\f114"; }
+.icon-audio:before { content: "\f115"; }
+.icon-code:before { content: "\f116"; }
+.icon-dataset:before { content: "\f117"; }
+.icon-dataverse:before { content: "\f118"; }
+.icon-document:before { content: "\f119"; }
+.icon-file:before { content: "\f11a"; }
+.icon-geodata:before { content: "\f11b"; }
+.icon-image:before { content: "\f11c"; }
+.icon-network:before { content: "\f11d"; }
+.icon-other:before { content: "\f11f"; }
+.icon-package:before { content: "\f120"; }
+.icon-tabular:before { content: "\f122"; }
+.icon-unlock:before { content: "\f123"; }
+.icon-video:before { content: "\f124"; }

doc/sphinx-guides/source/conf.py

@@ -222,7 +222,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['_static', '_static/fontcustom-preview.html']
 
 #html_js_files = []
 

doc/sphinx-guides/source/developers/fontcustom.rst

@@ -0,0 +1,102 @@
+===========
+Font Custom
+===========
+
+As mentioned under :ref:`style-guide-fontcustom` in the Style Guide, Dataverse uses `Font Custom`_ to create custom icon fonts.
+
+.. _Font Custom: https://github.com/FontCustom/fontcustom
+
+.. contents:: |toctitle|
+	:local:
+
+Previewing Icons
+----------------
+
+The process below updates a `preview page`_ that you can use to see how the icons look.
+
+.. _preview page: ../_static/fontcustom-preview.html
+
+In `scripts/icons/svg`_ in the source tree, you can see the SVG files that the icons are built from. 
+
+.. _scripts/icons/svg: https://github.com/IQSS/dataverse/tree/develop/scripts/icons
+
+Install Font Custom
+-------------------
+
+You'll need Font Custom and its dependencies installed if you want to update the icons.
+
+Ruby Version
+~~~~~~~~~~~~
+
+Font Custom is written in Ruby. Ruby 3.0 didn't "just work" with FontAwesome but Ruby 2.7 was fine.
+
+RVM is a good way to install a specific version of Ruby: https://rvm.io
+
+Install Dependencies and Font Custom Gem
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The brew commands below assume you are on a Mac. See :doc:`dev-environment` for more on ``brew``.
+
+.. code-block:: bash
+
+        brew tap bramstein/webfonttools
+        brew update
+        brew install woff2
+        brew install sfnt2woff
+        brew install fontforge
+        brew install eot-utils
+        gem install fontcustom
+
+
+(``brew install sfnt2woff`` isn't currently listed in the FontCustom README but it's in mentioned in https://github.com/FontCustom/fontcustom/pull/385)
+
+If ``fontcustom --help`` works now, you have it installed.
+
+Updating Icons
+--------------
+
+Navigate to ``scripts/icons`` in the source tree (or `online`_) and you will find:
+
+- An ``svg`` directory containing the "source" for the icons.
+- Scripts to update the icons.
+
+.. _online: https://github.com/IQSS/dataverse/tree/develop/scripts/icons
+
+There is a copy of these icons in both the app and the guides. We'll update the guides first because it's much quicker to iterate and notice any problems with the icons.
+
+Updating the Guides Icons
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Run ``docs.sh`` and then open ``../../doc/sphinx-guides/source/_static/fontcustom-preview.html`` in a browser to look at the icons. (This is the `preview page`_ mentioned above that gets incorporated in the next Sphinx build.)
+
+Update any files in the ``svg`` directory and run the script again to see any differences.
+
+Note that Font Custom creates font files with unique names. For this reason, we should remove the old files from git as we add the new ones. The script deletes the old files for you but in a step below we'll do a ``git add`` to stage this change.
+
+Updating the App Icons
+~~~~~~~~~~~~~~~~~~~~~~
+
+Assuming you're happy with how the icons look in the preview page in the guides, you can move on to updating the icons in the Dataverse app itself.
+
+This time the script is called ``app.sh`` and it works the same way with the addition of tweaking some URLs. Go ahead and run this script and do a full "clean and build" before making sure the changes are visible in the application.
+
+Committing Changes to Git
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As mentioned above, icons are in both the app and the docs. Again, because the filenames change, we should make sure the old files are removed from git.
+
+From the root of the repo, run the following:
+
+.. code-block:: bash
+
+        git add doc/sphinx-guides/source/_static
+        git add src/main/webapp/resources
+
+That should be enough to make sure old files are replaced by new ones. At this point, you can commit and make a pull request.
+
+Caveats About Font Custom
+-------------------------
+
+Font Custom is a useful tool and has an order of magnitude more stars on GitHub than its competitors. However, an `issue`_ suggests that the tool is somewhat abandoned. Its domain has expired but you can still get at what used to be its website at https://fontcustom.github.io/fontcustom/
+
+.. _issue: https://github.com/FontCustom/fontcustom/issues/321

doc/sphinx-guides/source/developers/index.rst

@@ -38,3 +38,4 @@ Developer Guide
    dataset-semantic-metadata-api
    dataset-migration-api 
    workflows
+   fontcustom

doc/sphinx-guides/source/style/foundations.rst

@@ -277,10 +277,12 @@ There are over 250 glyphs in font format from the Glyphicon Halflings set provid
    <span class="glyphicon glyphicon-user"></span>
    <span class="glyphicon glyphicon-lock"></span>
 
-FontCustom Icon Font
---------------------
+.. _style-guide-fontcustom:
+
+Font Custom Icon Font
+---------------------
 
-With the use of `FontCustom <https://github.com/FontCustom/fontcustom>`__ we were able to generate our own custom icon webfonts. We use these in the search result cards to help distinguish between Dataverse collection, dataset and file results.
+With the use of `Font Custom <https://github.com/FontCustom/fontcustom>`__ we generate our own custom icon fonts. We use these in the search result cards to help distinguish between Dataverse collection, dataset and file results.
 
 .. raw:: html
 
@@ -298,6 +300,7 @@ With the use of `FontCustom <https://github.com/FontCustom/fontcustom>`__ we wer
    <span class="icon-dataset text-dataset"></span>
    <span class="icon-file text-file"></span>
 
+The :doc:`/developers/fontcustom` section of the Developer Guide explains how to update these custom icons.
 
 Socicon Icon Font 
 -----------------

scripts/icons/.gitignore

@@ -0,0 +1,2 @@
+.fontcustom-manifest.json
+preview

scripts/icons/README.md

@@ -0,0 +1 @@
+See https://guides.dataverse.org/en/latest/developers/fontcustom.html

scripts/icons/app.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+# Filenames change each time so remove the old ones.
+rm ../../src/main/webapp/resources/fontcustom/*
+# Generate new files (see config file for paths).
+fontcustom compile -c fontcustom-app.yml
+# We want a fresh run each time since we have two scripts.
+rm .fontcustom-manifest.json
+# Use absolute src url path to "/resources..." 
+# We've always done it this way.
+# The sed command is extra verbose for precision and clarity.
+sed -i -e 's/url("\.\./url("\/resources/' ../../src/main/webapp/resources/css/fontcustom.css
+echo "Done! If all went well, you can see the icons at preview/fontcustom-preview.html"

scripts/icons/docs.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+# Filenames change each time so remove the old ones.
+rm ../../doc/sphinx-guides/source/_static/fontcustom/*
+# Generate new files (see config file for paths).
+fontcustom compile -c fontcustom-docs.yml
+# We want a fresh run each time since we have two scripts.
+rm .fontcustom-manifest.json

scripts/icons/fontcustom-app.yml

@@ -0,0 +1,99 @@
+# =============================================================================
+# Font Custom Configuration
+#   This file should live in the directory where you run `fontcustom compile`.
+#   For more info, visit <https://github.com/FontCustom/fontcustom>.
+# =============================================================================
+
+
+# -----------------------------------------------------------------------------
+# Project Info
+# -----------------------------------------------------------------------------
+
+# The font's name. Also determines the file names of generated templates.
+#font_name: icons
+
+# Format of CSS selectors. {{glyph}} is substituted for the glyph name.
+#css_selector: .i-{{glyph}}
+
+# Generate fonts without asset-busting hashes.
+#no_hash: true
+
+# Encode WOFF fonts into the generated CSS.
+#base64: true
+
+# Forces compilation, even if inputs have not changed
+force: true
+
+# Display (possibly useful) debugging messages.
+#debug: true
+
+# Hide status messages.
+#quiet: true
+
+# Copyright information.
+#copyright: 
+
+
+# -----------------------------------------------------------------------------
+# Input / Output Locations
+#   You can save generated fonts, CSS, and other files to different locations
+#   here. Font Custom can also read input vectors and templates from different
+#   places.
+#
+#   NOTE:
+#   - Be sure to preserve the whitespace in these YAML hashes.
+#   - INPUT[:vectors] and OUTPUT[:fonts] are required. Everything else is
+#     optional.
+#   - Specify output locations for custom templates by including their file
+#     names as the key.
+# -----------------------------------------------------------------------------
+
+input:
+  vectors: svg
+#  templates: my/templates
+
+output:
+  fonts: ../../src/main/webapp/resources/fontcustom
+  css: ../../src/main/webapp/resources/css
+  preview: preview
+#  my-custom-template.yml: path/to/template/output
+
+
+# -----------------------------------------------------------------------------
+# Templates
+#   A YAML array of templates and files to generate alongside fonts. Custom
+#   templates should be saved in the INPUT[:templates] directory and referenced
+#   by their base file name.
+#
+#   For Rails and Compass templates, set `preprocessor_path` as the relative
+#   path from OUTPUT[:css] to OUTPUT[:fonts]. By default, these are the same
+#   directory.
+#
+#   Included in Font Custom: preview, css, scss, scss-rails
+#   Default: css, preview
+# -----------------------------------------------------------------------------
+
+#templates:
+#- scss-rails
+#- preview
+#- my-custom-template.yml
+
+#preprocessor_path: ../fonts/
+
+
+# -----------------------------------------------------------------------------
+# Font Settings (defaults shown)
+# -----------------------------------------------------------------------------
+
+# Size (in pica points) for which your font is designed.
+#font_design_size: 16
+
+# The em size. Setting this will scale the entire font to the given size.
+#font_em: 512
+
+# The font's ascent and descent. Used to calculate the baseline.
+#font_ascent: 448
+#font_descent: 64
+
+# Horizontally fit glyphs to their individual vector widths.
+#autowidth: false