mkdocs-tacc 0.2.0__py3-none-any.whl

mkdocs_tacc/tacc_readthedocs/README.md

@@ -0,0 +1,11 @@
+# TACC Theme Based on MkDocs' ReadTheDocs Theme
+
+This theme is based on [MkDocs' "ReadTheDocs" theme](https://www.mkdocs.org/user-guide/choosing-your-theme/#readthedocs). To use:
+
+> [!CAUTION]
+> Do **not** copy these files to your project.
+
+> [!TIP]
+> Install the theme into your project. [Learn how.](../README.md#quick-start)
+
+The assets and configuration are unique for TACC. The templates are edits of [the templates of MkDocs' "ReadTheDocs" theme from v1.4.2+](https://github.com/mkdocs/mkdocs/blob/1.4.2/mkdocs/themes/readthedocs/).

mkdocs_tacc/tacc_readthedocs/css/tacc-theme/bootstrap.css

@@ -0,0 +1,39 @@
+/* to make embedded media responsive */
+/* https://getbootstrap.com/docs/4.0/utilities/embed/ */
+
+.embed-responsive {
+  position: relative;
+  display: block;
+  width: 100%;
+  padding: 0;
+  overflow: hidden;
+}
+.embed-responsive::before {
+  display: block;
+  content: "";
+}
+.embed-responsive .embed-responsive-item,
+.embed-responsive iframe,
+.embed-responsive embed,
+.embed-responsive object,
+.embed-responsive video {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  border: 0;
+}
+.embed-responsive-21by9::before {
+  padding-top: 42.857143%;
+}
+.embed-responsive-16by9::before {
+  padding-top: 56.25%;
+}
+.embed-responsive-4by3::before {
+  padding-top: 75%;
+}
+.embed-responsive-1by1::before {
+  padding-top: 100%;
+}

mkdocs_tacc/tacc_readthedocs/css/tacc-theme/core-docs.css

@@ -0,0 +1,90 @@
+/* TODO: Migrate some of this to TACC/Core-Styles' `core-styles.docs.css` */
+
+
+
+
+/* ELEMENTS */
+
+
+/* to ensure paragraph font size matches core-styles.docs.css */
+/* FAQ: If ineffectual, theme.css font size may match core-styles.docs.css */
+p {
+  font-size: inherit; /* to overwrite theme.css */
+}
+
+
+/* to prevent figure image overflow */
+figure {
+  max-width: 100%; /* mimics theme.css `.rst-content img` */
+}
+
+/* to add border around figures */
+figure {
+  border: var(--global-border--normal);
+}
+
+
+/* For edge-case headings */
+:is(h1, h2, h3, h4, h5, h6) > small,
+.understate:is(h1, h2, h3, h4, h5, h6) {
+    font-weight: normal;
+    margin-block: 0;
+}
+details > summary > :is(h1, h2, h3, h4, h5, h6) {
+    display: inline-block;
+}
+
+
+/* to prevent wrap of certain tags */
+u, /* "unarticulated" demarkation of phrases that should not wrap */
+code:not([class]):not(pre > *) /* free-form code lines should never wrap */ {
+  white-space: nowrap;
+}
+u {
+  text-decoration: none; /* to undo browser default */
+}
+
+
+
+
+/* COMPONENTS */
+
+/* Grid */
+
+.grid {
+  display: grid;
+  gap: var(--global-space--grid-gap);
+  grid-template-columns: 1fr 1fr;
+}
+
+
+/* Headings */
+
+/* to style text like an <h2>, <h3>, etc. */
+/* FAQ: Design wants <h3> on index page, but it should NOT show in nav */
+/* TODO: Either, find a solution that does not involve "fake header" class */
+/* TODO: Or, support fake headers in Core (must then define margins) */
+.h2 {
+  /* to mimic browser */
+  display: block;
+  margin-block-start: 0.83em;
+  margin-block-end: 0.83em;
+  margin-inline-start: 0px;
+  margin-inline-end: 0px;
+
+  /* to mimic core-styles.docs */
+  font-size: var(--global-font-size--xx-large);
+  font-weight: var(--bold);
+}
+.h3 {
+  /* to mimic browser */
+  display: block;
+  margin-block-start: 1em;
+  margin-block-end: 1em;
+  margin-inline-start: 0px;
+  margin-inline-end: 0px;
+
+  /* to mimic core-styles.docs */
+  font-size: var(--global-font-size--x-large);
+  font-weight: var(--bold);
+}

mkdocs_tacc/tacc_readthedocs/css/tacc-theme/core-styles.base.css

@@ -0,0 +1,8 @@
+/* to enable ReadTheDocs' fake links in nav */
+/* https://github.com/mkdocs/mkdocs/blob/1.4.2/mkdocs/themes/readthedocs/nav.html#L1 */
+/* https://github.com/TACC/Core-Styles/blob/v2.40.2/src/lib/_imports/elements/links.css#L9 */
+a:not([href]).reference.internal {
+  /* https://github.com/TACC/Core-Styles/blob/v2.40.2/src/lib/_imports/tools/x-link.css#L16-17 */
+  opacity: revert-layer;
+  pointer-events: revert-layer;
+}

mkdocs_tacc/tacc_readthedocs/css/tacc-theme/core-styles.docs.css

@@ -0,0 +1,46 @@
+/* To reduce padding in sections */
+.section--light,
+.section--muted,
+.section--dark {
+  --padding-top: 20px;
+  --padding-bottom: 20px;
+}
+
+
+/* To support .c-card on mobile (which Core-Styles does not do) */
+
+/* To add field of color in neg. space beside short image */
+/* FAQ: This field is only possibly shown:
+- at certain screen widths
+- for certain image dimensions */
+@media (576px <= width < 768px), (992px < width) {
+  [class*="card--image-"] {
+    overflow: hidden; /* hide box-shadow that would bleed outside of card */
+  }
+  .c-card--image-top > img,
+  .c-card--image-bottom > img {
+    box-shadow: 25vw 0 white; /* for short image on narrow screen */
+  }
+  .c-card--image-left > img,
+  .c-card--image-right > img {
+    box-shadow: 0 10vw black; /* for narrow image on wide screen */
+  }
+}
+
+/* To remove side-by-side layout when image becomes too small */
+@media (768px <= width < 992px), (width < 576px) {
+  .c-card--image-left,
+  .c-card--image-right {
+    padding: unset; /* overwrites .c-card--image-… */
+    display: block; /* overwrites .c-card--image-… */
+  }
+  .c-card--image-left > img,
+  .c-card--image-right > img {
+    margin-block: unset; /* undo .c-card--image-… */
+  }
+  .c-card--image-left > p,
+  .c-card--image-right > p {
+    padding: calc( var(--global-space--pattern-pad) / 2);
+    margin: 0; /* overwrites core-styles, bootstrap, ReadTheDocs */
+  }
+}

mkdocs_tacc/tacc_readthedocs/css/tacc-theme/highlight-js.css

@@ -0,0 +1,61 @@
+/* mkdocs.base.yml: theme: highlightjs, hljs_aliases */
+/* https://www.mkdocs.org/user-guide/choosing-your-theme/#readthedocs */
+
+/* To change style for each type of code block (HighlightJS or TACC) */
+pre.cmd-line code,
+code.language-cmd-line {
+  background: var(--global-color-primary--x-light);
+}
+pre.job-script code,
+code.language-job-script {
+  background: var(--global-color-accent--xxx-light);
+}
+pre.syntax code,
+code.language-syntax {
+  background: var(--global-color-tertiary--xx-light);
+}
+@supports selector(:has(*)) {
+  /* To support code blocks that are not using <code> (yet) */
+  pre.cmd-line:not(:has(code)) {
+    background: var(--global-color-primary--x-light);
+  }
+  pre.job-script:not(:has(code)) {
+    background: var(--global-color-accent--xxx-light);
+  }
+  pre.syntax:not(:has(code)) {
+    background: var(--global-color-tertiary--xx-light);
+  }
+}
+
+/* To disuade users from blind copy/paste-use of syntax */
+pre.syntax code,
+code.language-syntax {
+  -webkit-user-select: none;
+  user-select: none;
+}
+
+/* To replicate missing styles on TACC code blocks */
+pre.cmd-line code,
+pre.job-script code {
+  /* To replicate HighlightJS code blocks */
+  overflow-x: auto;
+}
+@supports selector(:has(*)) {
+  /* To support code blocks that are not using <code> (yet) */
+  pre.cmd-line:not(:has(code)),
+  pre.job-script:not(:has(code)) {
+    /* To replicate HighlightJS code blocks */
+    overflow-x: auto;
+
+    /* To replicate Core Styles code blocks */
+    display: inline-block;
+    padding: var(--global-space--x-small) var(--global-space--small);
+    border: var(--global-border-width--normal) solid var(--global-color-primary--light);
+    color: var(--global-color-primary--xx-dark);
+  }
+}
+
+/* To remove space above and below code block in a figure */
+figure pre.highlight {
+  margin-block: unset; /* undo browser */
+}

mkdocs_tacc/tacc_readthedocs/css/tacc-theme/mkdocs.css

@@ -0,0 +1,7 @@
+/* SEARCH */
+
+#mkdocs-search-results {
+  /* to mimic browser <h3> margin-block-start: 1em */
+  /* FAQ: 1em equals core-styles.docs h3 font size */
+  margin-top: var(--global-font-size--x-large);
+}

mkdocs_tacc/tacc_readthedocs/css/tacc-theme/pymdownx.css

@@ -0,0 +1,78 @@
+/* ADMONITION */
+/* https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/admonition/ */
+
+/* to add space between plugin blocks */
+.admonition,
+.tabbed-set {
+  margin-block: 1em;
+}
+
+/* to add space between messages & content */
+/* to remove empty paragraphs */
+/* SEE: /docs/code-examples.md */
+/* HELP: What markdown would avoid these? */
+.admonition p:empty {
+  display: none;
+}
+
+/* to add admonition icons */
+.admonition::before {
+  /* copied from .fa (only the active rules not overwritten by TACC) */
+  font-family: FontAwesome;
+  font-style: normal;
+  font-weight: 400;
+  line-height: 1;
+  text-decoration: inherit;
+  text-rendering: auto;
+  -webkit-font-smoothing: antialiased;
+}
+.admonition:is(.caution)::before { content: "\f071"; }
+.admonition:is(.important, .attention)::before { content: "\f12a"; }
+.admonition:is(.warning)::before { content: "\f00d"; }
+.admonition:is(.tip)::before { content: "\f0eb"; }
+.admonition:is(.note)::before { content: "\f040"; }
+.admonition:is(.hint)::before { content: "\f00c"; }
+.admonition:is(.error, .danger)::before { content: "\f00d"; }
+.admonition:is(.warning)::before {
+  color: transparent;
+  -webkit-text-stroke: var(--global-color-primary--xx-light) 2px;
+}
+
+
+/* to remove admonition title icon */
+.admonition-title::before { display: none; }
+
+
+/* to give admonition block content a backgroud */
+.admonition       div.tabbed-set,
+.admonition.note  pre > code,
+.admonition       table {
+  background-color: var(--global-color-background--app);
+}
+
+
+
+
+/* BLOCKS: TAB */
+/* https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/tab/ */
+/* TABBED */
+/* https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/ */
+/* https://github.com/TACC/Core-Styles/blob/main/src/lib/_imports/components/pymdownx--tabbed.css */
+
+/* to add Docs-specific styles */
+.tabbed-set {
+  border: var(--global-border-width--thick) solid var(--global-color-primary--dark);
+}
+
+/* to stretch tabs that just have a code block */
+.tabbed-content > pre:only-child {
+  margin-inline: calc( -1 * var(--buffer) );
+  margin-block: unset; /* overwrite core-style.docs */
+}
+.tabbed-content > pre:only-child > code {
+  border: unset; /* overwrite core-style.docs */
+  padding: var(--buffer); /* overwrite core-style.docs */
+
+  width: 100%; /* overwrite core-style.docs */
+  box-sizing: border-box; /* so `width: 100%` does not overflow */
+}

mkdocs_tacc/tacc_readthedocs/css/tacc-theme/python-markdown.css

@@ -0,0 +1,56 @@
+/* TOC */
+/* https://python-markdown.github.io/extensions/toc/#usage */
+/* RFE: Support via Core-Styles class */
+
+.headerlink {
+  font-size: var(--global-font-size--x-large);
+  text-decoration: none;
+}
+
+@supports selector(:has(*)) {
+
+  /* to reposition permalink */
+  /* NOTE: Unnecessary if MkDocs config sets `permalink_leading: true` */
+  /* https://github.com/mkdocs/mkdocs/blob/1.5.0/pyproject.toml#L39 */
+  :has(> .headerlink) {
+    position: relative;
+  }
+  .headerlink {
+    position: absolute;
+
+    /* to add space between it and heading */
+    --x-space: 0.5em;
+    padding-right: var(--x-space);
+
+    /* to move to the left of the heading */
+    left: 0;
+    --x-offset: calc( 1ch + var(--x-space) );
+
+    /* to vertically center */
+    top: 50%;
+    --y-offset: 50%;
+
+    transform: translate(
+      calc( -1 * var(--x-offset)),
+      calc( -1 * var(--y-offset))
+    );
+  }
+
+  /* to use link color only on hover, otherwise use pale text color */
+  .headerlink:not(:hover) {
+    color: inherit;
+    opacity: 0.5;
+  }
+  /* to hide except on hover over it or heading */
+  .headerlink:not(:hover, :hover > *) {
+    opacity: 0;
+  }
+
+}
+@supports not selector(:has(*)) {
+
+  .headerlink {
+    margin-left: 0.5ch;
+  }
+
+}