mkdocs-tacc 0.2.0__tar.gz

mkdocs_tacc-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Texas Advanced Computing Center (TACC)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mkdocs_tacc-0.2.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.3
+Name: mkdocs-tacc
+Version: 0.2.0
+Summary: TACC ReadTheDocs theme for MkDocs
+License: MIT License
+         
+         Copyright (c) 2023 Texas Advanced Computing Center (TACC)
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Author: TACC COA CMD
+Author-email: coa-cmd@tacc.utexas.edu
+Maintainer: TACC COA CMD
+Maintainer-email: coa-cmd@tacc.utexas.edu
+Requires-Python: >=3.10,<3.13
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: MkDocs
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: BSD License
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Documentation
+Provides-Extra: i18n
+Requires-Dist: mkdocs (==1.4.3)
+Requires-Dist: mkdocs-exclude-search (>=0.6.5)
+Requires-Dist: mkdocs[i18n] (==1.4.3) ; extra == "i18n"
+Requires-Dist: pymdown-extensions (>=10.4.0)
+Project-URL: changelog, https://github.com/TACC/Core-Docs/releases
+Project-URL: github, https://github.com/TACC/Core-Docs
+Project-URL: issues, https://github.com/TACC/Core-Docs/issues
+Description-Content-Type: text/markdown
+
+# TACC MkDocs Theme & Guide & Demo
+
+A guide and demo for [TACC](https://www.tacc.utexas.edu/)'s [MkDocs](https://www.mkdocs.org/) documentation theme based on MkDocs' own [ReadTheDocs theme](https://www.mkdocs.org/user-guide/choosing-your-theme/#readthedocs) but with a [TACC styling and features](https://docs.tacc.utexas.edu/).
+
+## Quick Start
+
+<!-- Keep these steps synced with /docs/index.md -->
+
+1. Install the theme e.g.
+
+    ```shell
+    pip install mkdocs-tacc
+    ```
+
+2. Use the theme in your MkDocs project; set —
+
+    ```yaml
+    theme:
+        name: tacc_readthedocs
+    ```
+
+    — in your `mkdocs.yml`.
+
+3. Include _at least_ the [minimum set of extensions] —
+
+    ```yaml
+    markdown_extensions:
+      - toc:
+          permalink: "" # i.e. `true` but without "¶"
+          permalink_class: headerlink fa fa-link
+          permalink_title: Link to Heading
+    ```
+
+    — in your `mkdocs.yml`.
+
+[core extensions]: ./docs/extensions.md#core-extensions
+
+Learn to [configure](./docs/configure.md), [customize](./docs/customize.md), and [extend](./docs/extensions.md) your MkDocs site.
+
+## Known Clients
+
+| Status | Repository |
+| - | - |
+| Active | None |
+| Upcoming | [TACC-Docs](https://github.com/TACC/TACC-Docs)<br>[DesignSafe-CI/DS-User-Guide](https://github.com/DesignSafe-CI/DS-User-Guide) |
+| Potential | [TACC/containers_at_tacc](https://github.com/TACC/containers_at_tacc)<br>[TACC/life_sciences_ml_at_tacc](https://github.com/TACC/life_sciences_ml_at_tacc) |
+
+## For Developers
+
+Learn [how to **develop**](./DEVELOP.md) and [how to **deploy**](./DEPLOY.md).
+

mkdocs_tacc-0.2.0/README.md

@@ -0,0 +1,50 @@
+# TACC MkDocs Theme & Guide & Demo
+
+A guide and demo for [TACC](https://www.tacc.utexas.edu/)'s [MkDocs](https://www.mkdocs.org/) documentation theme based on MkDocs' own [ReadTheDocs theme](https://www.mkdocs.org/user-guide/choosing-your-theme/#readthedocs) but with a [TACC styling and features](https://docs.tacc.utexas.edu/).
+
+## Quick Start
+
+<!-- Keep these steps synced with /docs/index.md -->
+
+1. Install the theme e.g.
+
+    ```shell
+    pip install mkdocs-tacc
+    ```
+
+2. Use the theme in your MkDocs project; set —
+
+    ```yaml
+    theme:
+        name: tacc_readthedocs
+    ```
+
+    — in your `mkdocs.yml`.
+
+3. Include _at least_ the [minimum set of extensions] —
+
+    ```yaml
+    markdown_extensions:
+      - toc:
+          permalink: "" # i.e. `true` but without "¶"
+          permalink_class: headerlink fa fa-link
+          permalink_title: Link to Heading
+    ```
+
+    — in your `mkdocs.yml`.
+
+[core extensions]: ./docs/extensions.md#core-extensions
+
+Learn to [configure](./docs/configure.md), [customize](./docs/customize.md), and [extend](./docs/extensions.md) your MkDocs site.
+
+## Known Clients
+
+| Status | Repository |
+| - | - |
+| Active | None |
+| Upcoming | [TACC-Docs](https://github.com/TACC/TACC-Docs)<br>[DesignSafe-CI/DS-User-Guide](https://github.com/DesignSafe-CI/DS-User-Guide) |
+| Potential | [TACC/containers_at_tacc](https://github.com/TACC/containers_at_tacc)<br>[TACC/life_sciences_ml_at_tacc](https://github.com/TACC/life_sciences_ml_at_tacc) |
+
+## For Developers
+
+Learn [how to **develop**](./DEVELOP.md) and [how to **deploy**](./DEPLOY.md).

mkdocs_tacc-0.2.0/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-0.2.0/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-0.2.0/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-0.2.0/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-0.2.0/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-0.2.0/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-0.2.0/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-0.2.0/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-0.2.0/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;
+  }
+
+}