Theme fixes and more (#169)

* `color` prop for icon * Refactor GridTableOfContents to use icon color prop * `gridTOC` frontmatter data * GridTableOfContents component * Use GridTableOfContents in App * Use $min-font-size in global.scss * Fix styling for grid TOC * Rename GridTableOfContents to QuickLinks * Remove demo data * Fix quick links grid gap * `metaDescription` config for setting meta description tag * Fix _modules link on API references * Inline code styling copied from napari hub * Add custom Pygments code theme * Load scripts and stylesheets from HTML file * Fix styling for copy button * Add comments * Fix theme colors to be a11y friendly * Fix sphinx script loading for pages transitions * Use IconColorProps from #170
napari · Sep 23, 2021 · 15cab12 · 15cab12
1 parent a340f18
commit 15cab12
Show file tree

Hide file tree

Showing 15 changed files with 463 additions and 97 deletions.
diff --git a/.prettierignore b/.prettierignore
@@ -3,3 +3,4 @@
 theme/napari/*.html
 theme/napari/static
 theme.conf
+**/*.py
diff --git a/_config.yml b/_config.yml
@@ -47,6 +47,7 @@ sphinx:
     # html_theme: napari
     # html_theme_path:
     #   - theme
+    # pygments_style: theme.napari_code_theme.NapariCodeTheme
     pygments_style: solarized-dark
     templates_path:
       - '_templates'

diff --git a/package.json b/package.json
@@ -5,19 +5,19 @@
   "scripts": {
     "// Scripts for building napari.org for production": "",
     "build": "run-s clean build:*",
-    "build:docs": "jupyter-book build .",
+    "build:docs": "PYTHONPATH=$PWD jupyter-book build .",
     "build:next": "run-s next:*",
 
     "// Scripts for building and exporting the documentation using Next.js": "",
     "next:build": "next build",
-    "next:copy-public": "mkdir public && ts-node -P tsconfig.node.json scripts/copy-public-files",
+    "next:copy-public": "ts-node -P tsconfig.node.json scripts/copy-public-files",
     "next:export": "next export -o dist",
     "next:remove-extra-files": "rm -rf dist/index.html.html",
     "next:fix-dist-file-names": "ts-node -P tsconfig.node.json scripts/fix-dist-file-names",
 
     "// Scripts for running napari.org locally in development mode.": "",
     "dev": "yarn clean && mkdir -p _build/html && run-p dev:*",
-    "dev:server": "ts-node -P tsconfig.node.json scripts/dev-server",
+    "dev:server": "PYTHONPATH=$PWD ts-node -P tsconfig.node.json scripts/dev-server",
     "dev:tsm": "tsm -w -e default -p.@ theme/src 'theme/src/**/*.module.scss'",
 
     "// Scripts for cleaning build files.": "",

diff --git a/pages/[[...parts]].tsx b/pages/[[...parts]].tsx
@@ -5,7 +5,6 @@ import {
 } from 'next';
 import Head from 'next/head';
 import { useRouter } from 'next/router';
-import Script from 'next/script';
 import { resolve } from 'path';
 import { ParsedUrlQuery } from 'querystring';
 import { useEffect } from 'react';
@@ -124,49 +123,6 @@ export default function Page({ state }: Props) {
         </title>
       </Head>
 
-      {/* Include static JS scripts required by search page. */}
-      {isSearch && (
-        <>
-          {/*
-            The `documentation_options.js` script fetches the documentation URL
-            root from a DOM node with the id `documentation_options`. This is
-            always set to `./` for the search page.
-          */}
-          <div id="documentation_options" data-url_root="./" />
-
-          {/*
-            Scripts that should load before interactive. This is mostly so that
-            the scripts required by `searchtools.js` are ready before execution.
-          */}
-          {[
-            'jquery.js',
-            'underscore.js',
-            'documentation_options.js',
-            'doctools.js',
-            'language_data.js',
-          ]
-            .map((src) => `/${src}`)
-            .map((src) => (
-              <Script strategy="beforeInteractive" key={src} src={src} />
-            ))}
-
-          {/*
-            Scripts for running the Jupyter Book search engine. The
-            `searchtools.js` script is for executing the search and the
-            `searchindex.js` contains searhc index data generated by Jupyter
-            Book.
-
-            Search execution will begin immediately when the page loads if the
-            search query parameter is provided.
-          */}
-          {['searchtools.js', 'searchindex.js']
-            .map((src) => `/${src}`)
-            .map((src) => (
-              <Script key={src} src={src} />
-            ))}
-        </>
-      )}
-
       <JupyterBookProvider {...state}>
         <App />
       </JupyterBookProvider>

diff --git a/scripts/copy-public-files.ts b/scripts/copy-public-files.ts
@@ -9,33 +9,28 @@ const BUILD_DIR = resolve(ROOT_DIR, '_build/html');
  * folder so that Next.js can access it
  */
 export async function copyPublicFiles(): Promise<void> {
-  const staticFiles = [
-    'pygments.css',
-    'jquery.js',
-    'underscore.js',
-    'documentation_options.js',
-    'doctools.js',
-    'language_data.js',
-    'searchtools.js',
-  ].map((file) => resolve(BUILD_DIR, '_static', file));
+  const staticFiles = resolve(BUILD_DIR, '_static');
   const searchIndexFile = resolve(BUILD_DIR, 'searchindex.js');
   const imageFiles = resolve(BUILD_DIR, '_images');
   const publicDirectory = resolve(ROOT_DIR, 'public');
+  const staticPublicDirectory = resolve(publicDirectory, '_static');
 
   // Remove public directory to ensure consistent rebuilds during development.
   if (await fs.pathExists(publicDirectory)) {
     await fs.remove(publicDirectory);
   }
 
+  // Create public directories so that concurrent file copies do not throw an error.
+  await fs.mkdir(publicDirectory);
+  await fs.mkdir(staticPublicDirectory);
+
   // Copy all files concurrently.
   await Promise.all([
-    ...staticFiles.map((file) =>
-      fs.copy(file, resolve(publicDirectory, basename(file))),
-    ),
+    fs.copy(staticFiles, staticPublicDirectory),
     fs.copy(imageFiles, resolve(publicDirectory, '_images')),
     fs.copy(
       searchIndexFile,
-      resolve(publicDirectory, basename(searchIndexFile)),
+      resolve(staticPublicDirectory, basename(searchIndexFile)),
     ),
   ]);
 }

diff --git a/theme/napari/page.html b/theme/napari/page.html
@@ -17,7 +17,7 @@
     </style>
 
     <link rel="shortcut icon" href="{{ pathto('_static/favicon.ico', 1) }}">
-    <link rel="stylesheet" href="{{ pathto('_static/dist/style.css', 1) }}">
+    <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}">
   </head>
 
   <body>
@@ -29,18 +29,13 @@
       <div id="global-toc">{{ toctree(includehidden=true, collapse=false) }}</div>
 
       <div id="page-body">
+        <div id="documentation_options" data-url_root="{{ pathto('', 1) }}"></div>
         {{ body }}
       </div>
 
       <div id="page-toc">{{ toc }}</div>
     </div>
 
-    <script
-      id="documentation_options"
-      data-url_root="{{ pathto('', 1) }}"
-      src="{{ pathto('_static/documentation_options.js', 1) }}"
-    ></script>
-
     <script data-dev src="/reload/reload.js"></script>
 
     <script data-dev type="module">
@@ -56,5 +51,24 @@
 
     <script type="module" src="{{ pathto('_static/dist/napari-theme.es.js', 1) }}"></script>
     <script nomodule defer src="{{ pathto('_static/dist/napari-theme.iife.js', 1) }}"></script>
+
+    <div id="scripts">
+      <script src="{{ pathto('_static/documentation_options.js', 1) }}"></script>
+
+      {%- block scripts -%}
+
+      {# Custom JS #}
+      {%- block regular_scripts -%}
+      {% for path in script_files -%}
+        {{ js_tag(path) }}
+      {% endfor -%}
+      {%- endblock regular_scripts -%}
+
+      {# Theme-related JavaScript code #}
+      {%- block theme_scripts -%}
+      {%- endblock -%}
+
+      {%- endblock scripts -%}
+    </div>
   </body>
 </html>
diff --git a/theme/napari_code_theme.py b/theme/napari_code_theme.py
@@ -0,0 +1,55 @@
+from pygments.style import Style
+from pygments.token import (
+  Comment,
+  Error,
+  Generic,
+  Keyword,
+  Literal,
+  Name,
+  Operator,
+  Punctuation,
+  String,
+)
+
+# Pygments style class based on GitHub code style:
+# https://git.io/Jz85x
+class NapariCodeTheme(Style):
+    background_color = "#f7f7f7"
+
+    styles = {
+          Comment:                "italic #6f6f6f",
+          Comment.Multiline:      "italic #6f6f6f",
+          Comment.Preproc:        "bold #6f6f6f",
+          Comment.Single:         "italic #6f6f6f",
+          Comment.Special:        "bold italic #6f6f6f",
+          Error:                  "bg:#e3d2d2 #a61717",
+          Generic.Deleted:        "bg:#ffdddd #000000",
+          Generic.Emph:           "italic #000000",
+          Generic.Error:          "#990000",
+          Generic.Heading:        "#6f6f6f",
+          Generic.Inserted:       "bg:#ddffdd #000000",
+          Generic.Output:         "#6f6f6f",
+          Generic.Prompt:         "#555555",
+          Generic.Strong:         "bold",
+          Generic.Subheading:     "#6f6f6f",
+          Generic.Traceback:      "#aa0000",
+          Keyword:                "bold #7518a1",
+          Literal.Number:         "#227b81",
+          Literal.String:         "#0074b8",
+          Name:                   '#000',
+          Name.Attribute:         "#7518a1",
+          Name.Builtin:           "bold #7518a1",
+          Name.Class:             "bold #5471a0",
+          Name.Constant:          "#7518a1",
+          Name.Decorator:         "bold #3c5d5d",
+          Name.Entity:            "#800080",
+          Name.Exception:         "bold #990000",
+          Name.Function:          "bold #004166",
+          Name.Label:             "bold #990000",
+          Name.Namespace:         "#555555",
+          Name.Tag:               "#000080",
+          Name.Variable:          "#7518a1",
+          Operator:               "#956441",
+          Punctuation:            '#000',
+          String:                 "#0074b8",
+    }
diff --git a/theme/src/components/App/App.module.scss b/theme/src/components/App/App.module.scss
@@ -1,33 +1,100 @@
+@use 'sass:math';
+
 .content {
-  :global {
-    // Render Markdown badges as inline elements.
-    p > a > img {
-      @apply inline-block m-0;
+  // Render Markdown badges as inline elements.
+  p > a > img {
+    /*
+      Make images inline in markdown. By default, Tailwind will set all `img`
+      tags to `display: block`:
+      https://tailwindcss.com/docs/preflight#images-are-block-level.
+
+      We don't want this for markdown because it affects rendering of markdown
+      badges. Usually devs will include a bunch of badges together at the top
+      of the file. If all of the images are `display: block` by default, the
+      badges get rendered as a column instead of as row.
+
+      Also, having images rendered as blocks in markdown is redundant because
+      the markdown renderer will automatically wrap the image in a <p> tag to
+      ensure that the image is displayed as a block.
+    */
+    @apply inline;
+
+    // Remove extra margin added by prose.
+    @apply m-0;
+  }
+
+  // Inline text styles.
+  code {
+    @apply text-base font-normal p-1;
+
+    background: #f7f7f7;
+
+    &::before,
+    &::after {
+      content: '';
     }
   }
-}
 
-.search {
+  h2 {
+    /*
+      The designs requires a 35px margin between the heading and the top of
+      the viewport when scrolling to a heading.
+
+      TODO There's currently no support for this in Safari yet. We'll need to
+      implement a solution in TypeScript.
+      https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-margin-top
+    */
+    scroll-margin-top: #{math.div(35px, 16px)}rem;
+  }
+
+  pre {
+    @apply text-black m-0 p-0;
+
+    // The Tailwind prose class adds a background around pre elements.
+    background: none;
+  }
+
   :global {
-    // Remove list item left dot.
-    li::before {
-      display: none;
+    .highlight {
+      @apply relative p-4;
     }
 
-    ul > li {
-      @apply border-t last:border-b border-black;
-      @apply pl-0 py-2;
+    .copybtn {
+      @apply absolute top-4 right-4 bg-white;
+      @apply opacity-0 transition-opacity;
     }
 
+    .copybtn img {
+      @apply m-0 w-6 h-6;
+    }
+
+    .highlight:hover .copybtn {
+      @apply opacity-100;
+    }
+  }
+}
+
+.search {
+  // Remove list item left dot.
+  li::before {
+    display: none;
+  }
+
+  ul > li {
+    @apply border-t last:border-b border-black;
+    @apply pl-0 py-2;
+  }
+
+  h2 {
+    @apply m-0;
+  }
+
+  :global {
     // Search result highlighting.
     .highlighted {
       @apply bg-napari-light p-0.5;
     }
 
-    h2 {
-      @apply m-0;
-    }
-
     .search-summary {
       @apply m-0 mt-4;
     }