From baa7b51787d34dd9a347be35b904dd530d2c9dc7 Mon Sep 17 00:00:00 2001 From: Jon Lockwood Date: Sun, 28 Aug 2022 12:31:12 +0930 Subject: [PATCH] refactor(theme): migrated from website repo migrated the files required to create the themes for this mkdocs site. MR !1 #1 --- custom-plugins/mkdocs-plugin-tags/.gitignore | 125 ++++ custom-plugins/mkdocs-plugin-tags/LICENSE.md | 7 + custom-plugins/mkdocs-plugin-tags/MANIFEST.in | 2 + custom-plugins/mkdocs-plugin-tags/README.md | 128 ++++ .../mkdocs-plugin-tags/requirements.txt | 1 + custom-plugins/mkdocs-plugin-tags/setup.cfg | 27 + custom-plugins/mkdocs-plugin-tags/setup.py | 19 + .../mkdocs-plugin-tags/tags/__init__.py | 3 + .../mkdocs-plugin-tags/tags/_version.py | 644 ++++++++++++++++++ .../mkdocs-plugin-tags/tags/plugin.py | 151 ++++ .../tags/templates/tags.md.template | 7 + stylesheets/extra.css | 121 ++++ theme-overrides/.icons/brand/docker.svg | 1 + theme-overrides/article.html | 27 + theme-overrides/article_list.html | 38 ++ theme-overrides/home.html | 68 ++ theme-overrides/manual.html | 63 ++ .../partials/article_extended_preview.html | 7 + .../partials/article_metadata.html | 32 + theme-overrides/partials/article_social.html | 17 + theme-overrides/partials/footer.html | 14 + theme-overrides/sitemap.xml | 12 + 22 files changed, 1514 insertions(+) create mode 100755 custom-plugins/mkdocs-plugin-tags/.gitignore create mode 100755 custom-plugins/mkdocs-plugin-tags/LICENSE.md create mode 100755 custom-plugins/mkdocs-plugin-tags/MANIFEST.in create mode 100755 custom-plugins/mkdocs-plugin-tags/README.md create mode 100755 custom-plugins/mkdocs-plugin-tags/requirements.txt create mode 100755 custom-plugins/mkdocs-plugin-tags/setup.cfg create mode 100755 custom-plugins/mkdocs-plugin-tags/setup.py create mode 100755 custom-plugins/mkdocs-plugin-tags/tags/__init__.py create mode 100755 custom-plugins/mkdocs-plugin-tags/tags/_version.py create mode 100755 custom-plugins/mkdocs-plugin-tags/tags/plugin.py create mode 100755 custom-plugins/mkdocs-plugin-tags/tags/templates/tags.md.template create mode 100644 stylesheets/extra.css create mode 100755 theme-overrides/.icons/brand/docker.svg create mode 100755 theme-overrides/article.html create mode 100755 theme-overrides/article_list.html create mode 100755 theme-overrides/home.html create mode 100755 theme-overrides/manual.html create mode 100755 theme-overrides/partials/article_extended_preview.html create mode 100755 theme-overrides/partials/article_metadata.html create mode 100755 theme-overrides/partials/article_social.html create mode 100755 theme-overrides/partials/footer.html create mode 100755 theme-overrides/sitemap.xml diff --git a/custom-plugins/mkdocs-plugin-tags/.gitignore b/custom-plugins/mkdocs-plugin-tags/.gitignore new file mode 100755 index 0000000..f56be71 --- /dev/null +++ b/custom-plugins/mkdocs-plugin-tags/.gitignore @@ -0,0 +1,125 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +pip-wheel-metadata/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +# docs/_build/ + +# PyBuilder +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +.python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# celery beat schedule file +celerybeat-schedule + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ diff --git a/custom-plugins/mkdocs-plugin-tags/LICENSE.md b/custom-plugins/mkdocs-plugin-tags/LICENSE.md new file mode 100755 index 0000000..4720011 --- /dev/null +++ b/custom-plugins/mkdocs-plugin-tags/LICENSE.md @@ -0,0 +1,7 @@ +# License + +Copyright (C) 2021 No Fuss Computing + +All Rights Reserved. + +Not yet suitable for public release. diff --git a/custom-plugins/mkdocs-plugin-tags/MANIFEST.in b/custom-plugins/mkdocs-plugin-tags/MANIFEST.in new file mode 100755 index 0000000..ebd0c96 --- /dev/null +++ b/custom-plugins/mkdocs-plugin-tags/MANIFEST.in @@ -0,0 +1,2 @@ +include versioneer.py +include tags/_version.py diff --git a/custom-plugins/mkdocs-plugin-tags/README.md b/custom-plugins/mkdocs-plugin-tags/README.md new file mode 100755 index 0000000..b473fd9 --- /dev/null +++ b/custom-plugins/mkdocs-plugin-tags/README.md @@ -0,0 +1,128 @@ +# No Fuss Computing's Tags Plugin for MKDocs + +Modified version from: [github.com/ginsburgnm/mkdocs-plugin-tags](https://github.com/ginsburgnm/mkdocs-plugin-tags) + +## Previous Readme below - tags + +Support for tags in the yaml-metadata in the header of markdown files. + +Extracts this metadata and creates a "Tags" page which lists all tags +and all pages for each tag. + +## Quick Demo + +Install this plugin (it will also install mkdocs if required) + +```bash +pip install mkdocs-plugin-tags +``` + +Create a new documentation folder: + +```bash +mkdocs new demo +``` + +Edit the `.md` files to add initial metadata. Currently, the metadata has to be +enclosed in `---` lines, and must include a `title:` property +(otherwise the page will appear as "untitled" in the tags page). So, for example: + +```bash +cd demo +cd docs +cat > index.md +--- +title: Welcome +tags: + - testing + - unimportant +--- +# Welcome to MkDocs + +For full documentation visit [mkdocs.org](https://mkdocs.org). + +^D +``` + +Edit `mkdocs.yml` to include this plugin: + +```yaml +plugins: + - tags: +``` + +Run the server: + +```bash +mkdocs serve --livereload +``` + +Visit the URL `/tags` (it should appear in the nav panel). +This is an auto-generated page which contains the tags as level 2 headers, +and under each tag, a listing of the pages which declare that tag in the +metadata section. + +![example screenshot](doc/imgs/screenshot.png) + +## How it works + +On each build (even with `--livereload`), all the `.md` files composing the +site are scanned, their "triple-dash-delimted" yaml header is extracted and +parsed, and the list of tags is collected. + +After that, a new temporal file is created (by default in `aux/tags.md`, but +this is customizable) which contains the generated tags page, in markdown +format. This file is not in the documents folder to avoid retriggering a +build, but it is added to the list of files to be converted to HTML by mkdocs. + +## Customization + +The layout of the tags page is a markdown file with jinja2 embedded contents. +The package provides such a template by default, with the following content: + +```markdown +--- +title: Tags +--- +# Contents grouped by tag + +{% for tag, pages in tags %} + +## {{tag}} +{% for page in pages %} + * [{{page.title}}]({{page.filename}}) +{% endfor %} + +{% endfor %} +``` + +You can style the `h2.tag` element via CSS, if you want. + +You can also provide your own markdown template, in case that you want a +different layout or metadata. The `page` object contains all the metadata +in a mkdocs page, and in addition a `.filename` attribute, which contains +the file name of the source of the page (relative to the docs folder), +which can be used to link to that page. + +The full customizable options for the plugin are: + +* `tags_folder`: Folder in which the auxiliar tags markdown file will be written + (`aux` by default, relative to the folder in which `mkdocs` is invoked). + It can be set to an absolute path, such as `/tmp/mysite/aux`. + The required folders are created. +* `tags_template`: path to the file which contains the markdown-jinja template + for the tags page. It is `None` by default, which means that the + package-provided template is used. It can be an absolute path, + or relative to the folder in which `mkdocs` is run. +* `css_name`: this allows you to pick what name styles the tag that appears on + the top of the page that contains a tag. This way things won't be overloaded + +For example, this can be put at `mkdocs.yaml`: + +```yaml +plugins: + - search + - tags: + tags_folder: /tmp/mysite/aux + tags_template: docs/theme/tags.md.template +``` diff --git a/custom-plugins/mkdocs-plugin-tags/requirements.txt b/custom-plugins/mkdocs-plugin-tags/requirements.txt new file mode 100755 index 0000000..fe9469e --- /dev/null +++ b/custom-plugins/mkdocs-plugin-tags/requirements.txt @@ -0,0 +1 @@ +mkdocs==1.2.3 diff --git a/custom-plugins/mkdocs-plugin-tags/setup.cfg b/custom-plugins/mkdocs-plugin-tags/setup.cfg new file mode 100755 index 0000000..7a66196 --- /dev/null +++ b/custom-plugins/mkdocs-plugin-tags/setup.cfg @@ -0,0 +1,27 @@ +[metadata] +name = mkdocs-plugin-tags +author = No Fuss Computing +author_email = helpdesk@nofusscomputing.com +url = https://gitlab.com/nofusscomputing/infrastructure/website +description = "Create tags in mkdocs" +long_description_content_type = text/markdown +long_description = file: README.md +license = MIT +keywords = "mkdocs python markdown tags" +classifiers = + Intended Audience :: Developers + License :: OSI Approved :: MIT License + Operating System :: OS Independent + Intended Audience :: Information Technology + Programming Language :: Python :: 3.6 + Programming Language :: Python :: 3.7 + Programming Language :: Python :: 3.8 + Topic :: Security :: Cryptography + +[versioneer] +VCS = git +style = pep440 +versionfile_source = tags/_version.py +versionfile_build = tags/_version.py +tag_prefix = +parentdir_prefix = tags- diff --git a/custom-plugins/mkdocs-plugin-tags/setup.py b/custom-plugins/mkdocs-plugin-tags/setup.py new file mode 100755 index 0000000..68d5092 --- /dev/null +++ b/custom-plugins/mkdocs-plugin-tags/setup.py @@ -0,0 +1,19 @@ +""" +Setup the plugin +""" +from setuptools import setup, find_packages + +setup( + version='0.0.1', + python_requires='>=3.6', + install_requires=[ + 'mkdocs==1.2.3', + ], + packages=find_packages(exclude=['*.tests']), + package_data={'tags': ['templates/*.md.template']}, + entry_points={ + 'mkdocs.plugins': [ + 'tags = tags.plugin:TagsPlugin' + ] + } +) diff --git a/custom-plugins/mkdocs-plugin-tags/tags/__init__.py b/custom-plugins/mkdocs-plugin-tags/tags/__init__.py new file mode 100755 index 0000000..ecd3379 --- /dev/null +++ b/custom-plugins/mkdocs-plugin-tags/tags/__init__.py @@ -0,0 +1,3 @@ + +from . import _version +__version__ = _version.get_versions()['version'] diff --git a/custom-plugins/mkdocs-plugin-tags/tags/_version.py b/custom-plugins/mkdocs-plugin-tags/tags/_version.py new file mode 100755 index 0000000..adc1549 --- /dev/null +++ b/custom-plugins/mkdocs-plugin-tags/tags/_version.py @@ -0,0 +1,644 @@ + +# This file helps to compute a version number in source trees obtained from +# git-archive tarball (such as those provided by githubs download-from-tag +# feature). Distribution tarballs (built by setup.py sdist) and build +# directories (produced by setup.py build) will contain a much shorter file +# that just contains the computed version number. + +# This file is released into the public domain. Generated by +# versioneer-0.21 (https://github.com/python-versioneer/python-versioneer) + +"""Git implementation of _version.py.""" + +import errno +import os +import re +import subprocess +import sys +from typing import Callable, Dict + + +def get_keywords(): + """Get the keywords needed to look up the version information.""" + # these strings will be replaced by git during git-archive. + # setup.py/versioneer.py will grep for the variable names, so they must + # each be defined on a line of their own. _version.py will just call + # get_keywords(). + git_refnames = "$Format:%d$" + git_full = "$Format:%H$" + git_date = "$Format:%ci$" + keywords = {"refnames": git_refnames, "full": git_full, "date": git_date} + return keywords + + +class VersioneerConfig: + """Container for Versioneer configuration parameters.""" + + +def get_config(): + """Create, populate and return the VersioneerConfig() object.""" + # these strings are filled in when 'setup.py versioneer' creates + # _version.py + cfg = VersioneerConfig() + cfg.VCS = "git" + cfg.style = "pep440" + cfg.tag_prefix = "" + cfg.parentdir_prefix = "tags-" + cfg.versionfile_source = "tags/_version.py" + cfg.verbose = False + return cfg + + +class NotThisMethod(Exception): + """Exception raised if a method is not valid for the current scenario.""" + + +LONG_VERSION_PY: Dict[str, str] = {} +HANDLERS: Dict[str, Dict[str, Callable]] = {} + + +def register_vcs_handler(vcs, method): # decorator + """Create decorator to mark a method as the handler of a VCS.""" + def decorate(f): + """Store f in HANDLERS[vcs][method].""" + if vcs not in HANDLERS: + HANDLERS[vcs] = {} + HANDLERS[vcs][method] = f + return f + return decorate + + +def run_command(commands, args, cwd=None, verbose=False, hide_stderr=False, + env=None): + """Call the given command(s).""" + assert isinstance(commands, list) + process = None + for command in commands: + try: + dispcmd = str([command] + args) + # remember shell=False, so use git.cmd on windows, not just git + process = subprocess.Popen([command] + args, cwd=cwd, env=env, + stdout=subprocess.PIPE, + stderr=(subprocess.PIPE if hide_stderr + else None)) + break + except OSError: + e = sys.exc_info()[1] + if e.errno == errno.ENOENT: + continue + if verbose: + print("unable to run %s" % dispcmd) + print(e) + return None, None + else: + if verbose: + print("unable to find command, tried %s" % (commands,)) + return None, None + stdout = process.communicate()[0].strip().decode() + if process.returncode != 0: + if verbose: + print("unable to run %s (error)" % dispcmd) + print("stdout was %s" % stdout) + return None, process.returncode + return stdout, process.returncode + + +def versions_from_parentdir(parentdir_prefix, root, verbose): + """Try to determine the version from the parent directory name. + + Source tarballs conventionally unpack into a directory that includes both + the project name and a version string. We will also support searching up + two directory levels for an appropriately named parent directory + """ + rootdirs = [] + + for _ in range(3): + dirname = os.path.basename(root) + if dirname.startswith(parentdir_prefix): + return {"version": dirname[len(parentdir_prefix):], + "full-revisionid": None, + "dirty": False, "error": None, "date": None} + rootdirs.append(root) + root = os.path.dirname(root) # up a level + + if verbose: + print("Tried directories %s but none started with prefix %s" % + (str(rootdirs), parentdir_prefix)) + raise NotThisMethod("rootdir doesn't start with parentdir_prefix") + + +@register_vcs_handler("git", "get_keywords") +def git_get_keywords(versionfile_abs): + """Extract version information from the given file.""" + # the code embedded in _version.py can just fetch the value of these + # keywords. When used from setup.py, we don't want to import _version.py, + # so we do it with a regexp instead. This function is not used from + # _version.py. + keywords = {} + try: + with open(versionfile_abs, "r") as fobj: + for line in fobj: + if line.strip().startswith("git_refnames ="): + mo = re.search(r'=\s*"(.*)"', line) + if mo: + keywords["refnames"] = mo.group(1) + if line.strip().startswith("git_full ="): + mo = re.search(r'=\s*"(.*)"', line) + if mo: + keywords["full"] = mo.group(1) + if line.strip().startswith("git_date ="): + mo = re.search(r'=\s*"(.*)"', line) + if mo: + keywords["date"] = mo.group(1) + except OSError: + pass + return keywords + + +@register_vcs_handler("git", "keywords") +def git_versions_from_keywords(keywords, tag_prefix, verbose): + """Get version information from git keywords.""" + if "refnames" not in keywords: + raise NotThisMethod("Short version file found") + date = keywords.get("date") + if date is not None: + # Use only the last line. Previous lines may contain GPG signature + # information. + date = date.splitlines()[-1] + + # git-2.2.0 added "%cI", which expands to an ISO-8601 -compliant + # datestamp. However we prefer "%ci" (which expands to an "ISO-8601 + # -like" string, which we must then edit to make compliant), because + # it's been around since git-1.5.3, and it's too difficult to + # discover which version we're using, or to work around using an + # older one. + date = date.strip().replace(" ", "T", 1).replace(" ", "", 1) + refnames = keywords["refnames"].strip() + if refnames.startswith("$Format"): + if verbose: + print("keywords are unexpanded, not using") + raise NotThisMethod("unexpanded keywords, not a git-archive tarball") + refs = {r.strip() for r in refnames.strip("()").split(",")} + # starting in git-1.8.3, tags are listed as "tag: foo-1.0" instead of + # just "foo-1.0". If we see a "tag: " prefix, prefer those. + TAG = "tag: " + tags = {r[len(TAG):] for r in refs if r.startswith(TAG)} + if not tags: + # Either we're using git < 1.8.3, or there really are no tags. We use + # a heuristic: assume all version tags have a digit. The old git %d + # expansion behaves like git log --decorate=short and strips out the + # refs/heads/ and refs/tags/ prefixes that would let us distinguish + # between branches and tags. By ignoring refnames without digits, we + # filter out many common branch names like "release" and + # "stabilization", as well as "HEAD" and "master". + tags = {r for r in refs if re.search(r'\d', r)} + if verbose: + print("discarding '%s', no digits" % ",".join(refs - tags)) + if verbose: + print("likely tags: %s" % ",".join(sorted(tags))) + for ref in sorted(tags): + # sorting will prefer e.g. "2.0" over "2.0rc1" + if ref.startswith(tag_prefix): + r = ref[len(tag_prefix):] + # Filter out refs that exactly match prefix or that don't start + # with a number once the prefix is stripped (mostly a concern + # when prefix is '') + if not re.match(r'\d', r): + continue + if verbose: + print("picking %s" % r) + return {"version": r, + "full-revisionid": keywords["full"].strip(), + "dirty": False, "error": None, + "date": date} + # no suitable tags, so version is "0+unknown", but full hex is still there + if verbose: + print("no suitable tags, using unknown + full revision id") + return {"version": "0+unknown", + "full-revisionid": keywords["full"].strip(), + "dirty": False, "error": "no suitable tags", "date": None} + + +@register_vcs_handler("git", "pieces_from_vcs") +def git_pieces_from_vcs(tag_prefix, root, verbose, runner=run_command): + """Get version from 'git describe' in the root of the source tree. + + This only gets called if the git-archive 'subst' keywords were *not* + expanded, and _version.py hasn't already been rewritten with a short + version string, meaning we're inside a checked out source tree. + """ + GITS = ["git"] + TAG_PREFIX_REGEX = "*" + if sys.platform == "win32": + GITS = ["git.cmd", "git.exe"] + TAG_PREFIX_REGEX = r"\*" + + _, rc = runner(GITS, ["rev-parse", "--git-dir"], cwd=root, + hide_stderr=True) + if rc != 0: + if verbose: + print("Directory %s not under git control" % root) + raise NotThisMethod("'git rev-parse --git-dir' returned error") + + # if there is a tag matching tag_prefix, this yields TAG-NUM-gHEX[-dirty] + # if there isn't one, this yields HEX[-dirty] (no NUM) + describe_out, rc = runner(GITS, ["describe", "--tags", "--dirty", + "--always", "--long", + "--match", + "%s%s" % (tag_prefix, TAG_PREFIX_REGEX)], + cwd=root) + # --long was added in git-1.5.5 + if describe_out is None: + raise NotThisMethod("'git describe' failed") + describe_out = describe_out.strip() + full_out, rc = runner(GITS, ["rev-parse", "HEAD"], cwd=root) + if full_out is None: + raise NotThisMethod("'git rev-parse' failed") + full_out = full_out.strip() + + pieces = {} + pieces["long"] = full_out + pieces["short"] = full_out[:7] # maybe improved later + pieces["error"] = None + + branch_name, rc = runner(GITS, ["rev-parse", "--abbrev-ref", "HEAD"], + cwd=root) + # --abbrev-ref was added in git-1.6.3 + if rc != 0 or branch_name is None: + raise NotThisMethod("'git rev-parse --abbrev-ref' returned error") + branch_name = branch_name.strip() + + if branch_name == "HEAD": + # If we aren't exactly on a branch, pick a branch which represents + # the current commit. If all else fails, we are on a branchless + # commit. + branches, rc = runner(GITS, ["branch", "--contains"], cwd=root) + # --contains was added in git-1.5.4 + if rc != 0 or branches is None: + raise NotThisMethod("'git branch --contains' returned error") + branches = branches.split("\n") + + # Remove the first line if we're running detached + if "(" in branches[0]: + branches.pop(0) + + # Strip off the leading "* " from the list of branches. + branches = [branch[2:] for branch in branches] + if "master" in branches: + branch_name = "master" + elif not branches: + branch_name = None + else: + # Pick the first branch that is returned. Good or bad. + branch_name = branches[0] + + pieces["branch"] = branch_name + + # parse describe_out. It will be like TAG-NUM-gHEX[-dirty] or HEX[-dirty] + # TAG might have hyphens. + git_describe = describe_out + + # look for -dirty suffix + dirty = git_describe.endswith("-dirty") + pieces["dirty"] = dirty + if dirty: + git_describe = git_describe[:git_describe.rindex("-dirty")] + + # now we have TAG-NUM-gHEX or HEX + + if "-" in git_describe: + # TAG-NUM-gHEX + mo = re.search(r'^(.+)-(\d+)-g([0-9a-f]+)$', git_describe) + if not mo: + # unparsable. Maybe git-describe is misbehaving? + pieces["error"] = ("unable to parse git-describe output: '%s'" + % describe_out) + return pieces + + # tag + full_tag = mo.group(1) + if not full_tag.startswith(tag_prefix): + if verbose: + fmt = "tag '%s' doesn't start with prefix '%s'" + print(fmt % (full_tag, tag_prefix)) + pieces["error"] = ("tag '%s' doesn't start with prefix '%s'" + % (full_tag, tag_prefix)) + return pieces + pieces["closest-tag"] = full_tag[len(tag_prefix):] + + # distance: number of commits since tag + pieces["distance"] = int(mo.group(2)) + + # commit: short hex revision ID + pieces["short"] = mo.group(3) + + else: + # HEX: no tags + pieces["closest-tag"] = None + count_out, rc = runner(GITS, ["rev-list", "HEAD", "--count"], cwd=root) + pieces["distance"] = int(count_out) # total number of commits + + # commit date: see ISO-8601 comment in git_versions_from_keywords() + date = runner(GITS, ["show", "-s", "--format=%ci", "HEAD"], cwd=root)[0].strip() + # Use only the last line. Previous lines may contain GPG signature + # information. + date = date.splitlines()[-1] + pieces["date"] = date.strip().replace(" ", "T", 1).replace(" ", "", 1) + + return pieces + + +def plus_or_dot(pieces): + """Return a + if we don't already have one, else return a .""" + if "+" in pieces.get("closest-tag", ""): + return "." + return "+" + + +def render_pep440(pieces): + """Build up version string, with post-release "local version identifier". + + Our goal: TAG[+DISTANCE.gHEX[.dirty]] . Note that if you + get a tagged build and then dirty it, you'll get TAG+0.gHEX.dirty + + Exceptions: + 1: no tags. git_describe was just HEX. 0+untagged.DISTANCE.gHEX[.dirty] + """ + if pieces["closest-tag"]: + rendered = pieces["closest-tag"] + if pieces["distance"] or pieces["dirty"]: + rendered += plus_or_dot(pieces) + rendered += "%d.g%s" % (pieces["distance"], pieces["short"]) + if pieces["dirty"]: + rendered += ".dirty" + else: + # exception #1 + rendered = "0+untagged.%d.g%s" % (pieces["distance"], + pieces["short"]) + if pieces["dirty"]: + rendered += ".dirty" + return rendered + + +def render_pep440_branch(pieces): + """TAG[[.dev0]+DISTANCE.gHEX[.dirty]] . + + The ".dev0" means not master branch. Note that .dev0 sorts backwards + (a feature branch will appear "older" than the master branch). + + Exceptions: + 1: no tags. 0[.dev0]+untagged.DISTANCE.gHEX[.dirty] + """ + if pieces["closest-tag"]: + rendered = pieces["closest-tag"] + if pieces["distance"] or pieces["dirty"]: + if pieces["branch"] != "master": + rendered += ".dev0" + rendered += plus_or_dot(pieces) + rendered += "%d.g%s" % (pieces["distance"], pieces["short"]) + if pieces["dirty"]: + rendered += ".dirty" + else: + # exception #1 + rendered = "0" + if pieces["branch"] != "master": + rendered += ".dev0" + rendered += "+untagged.%d.g%s" % (pieces["distance"], + pieces["short"]) + if pieces["dirty"]: + rendered += ".dirty" + return rendered + + +def pep440_split_post(ver): + """Split pep440 version string at the post-release segment. + + Returns the release segments before the post-release and the + post-release version number (or -1 if no post-release segment is present). + """ + vc = str.split(ver, ".post") + return vc[0], int(vc[1] or 0) if len(vc) == 2 else None + + +def render_pep440_pre(pieces): + """TAG[.postN.devDISTANCE] -- No -dirty. + + Exceptions: + 1: no tags. 0.post0.devDISTANCE + """ + if pieces["closest-tag"]: + if pieces["distance"]: + # update the post release segment + tag_version, post_version = pep440_split_post(pieces["closest-tag"]) + rendered = tag_version + if post_version is not None: + rendered += ".post%d.dev%d" % (post_version+1, pieces["distance"]) + else: + rendered += ".post0.dev%d" % (pieces["distance"]) + else: + # no commits, use the tag as the version + rendered = pieces["closest-tag"] + else: + # exception #1 + rendered = "0.post0.dev%d" % pieces["distance"] + return rendered + + +def render_pep440_post(pieces): + """TAG[.postDISTANCE[.dev0]+gHEX] . + + The ".dev0" means dirty. Note that .dev0 sorts backwards + (a dirty tree will appear "older" than the corresponding clean one), + but you shouldn't be releasing software with -dirty anyways. + + Exceptions: + 1: no tags. 0.postDISTANCE[.dev0] + """ + if pieces["closest-tag"]: + rendered = pieces["closest-tag"] + if pieces["distance"] or pieces["dirty"]: + rendered += ".post%d" % pieces["distance"] + if pieces["dirty"]: + rendered += ".dev0" + rendered += plus_or_dot(pieces) + rendered += "g%s" % pieces["short"] + else: + # exception #1 + rendered = "0.post%d" % pieces["distance"] + if pieces["dirty"]: + rendered += ".dev0" + rendered += "+g%s" % pieces["short"] + return rendered + + +def render_pep440_post_branch(pieces): + """TAG[.postDISTANCE[.dev0]+gHEX[.dirty]] . + + The ".dev0" means not master branch. + + Exceptions: + 1: no tags. 0.postDISTANCE[.dev0]+gHEX[.dirty] + """ + if pieces["closest-tag"]: + rendered = pieces["closest-tag"] + if pieces["distance"] or pieces["dirty"]: + rendered += ".post%d" % pieces["distance"] + if pieces["branch"] != "master": + rendered += ".dev0" + rendered += plus_or_dot(pieces) + rendered += "g%s" % pieces["short"] + if pieces["dirty"]: + rendered += ".dirty" + else: + # exception #1 + rendered = "0.post%d" % pieces["distance"] + if pieces["branch"] != "master": + rendered += ".dev0" + rendered += "+g%s" % pieces["short"] + if pieces["dirty"]: + rendered += ".dirty" + return rendered + + +def render_pep440_old(pieces): + """TAG[.postDISTANCE[.dev0]] . + + The ".dev0" means dirty. + + Exceptions: + 1: no tags. 0.postDISTANCE[.dev0] + """ + if pieces["closest-tag"]: + rendered = pieces["closest-tag"] + if pieces["distance"] or pieces["dirty"]: + rendered += ".post%d" % pieces["distance"] + if pieces["dirty"]: + rendered += ".dev0" + else: + # exception #1 + rendered = "0.post%d" % pieces["distance"] + if pieces["dirty"]: + rendered += ".dev0" + return rendered + + +def render_git_describe(pieces): + """TAG[-DISTANCE-gHEX][-dirty]. + + Like 'git describe --tags --dirty --always'. + + Exceptions: + 1: no tags. HEX[-dirty] (note: no 'g' prefix) + """ + if pieces["closest-tag"]: + rendered = pieces["closest-tag"] + if pieces["distance"]: + rendered += "-%d-g%s" % (pieces["distance"], pieces["short"]) + else: + # exception #1 + rendered = pieces["short"] + if pieces["dirty"]: + rendered += "-dirty" + return rendered + + +def render_git_describe_long(pieces): + """TAG-DISTANCE-gHEX[-dirty]. + + Like 'git describe --tags --dirty --always -long'. + The distance/hash is unconditional. + + Exceptions: + 1: no tags. HEX[-dirty] (note: no 'g' prefix) + """ + if pieces["closest-tag"]: + rendered = pieces["closest-tag"] + rendered += "-%d-g%s" % (pieces["distance"], pieces["short"]) + else: + # exception #1 + rendered = pieces["short"] + if pieces["dirty"]: + rendered += "-dirty" + return rendered + + +def render(pieces, style): + """Render the given version pieces into the requested style.""" + if pieces["error"]: + return {"version": "unknown", + "full-revisionid": pieces.get("long"), + "dirty": None, + "error": pieces["error"], + "date": None} + + if not style or style == "default": + style = "pep440" # the default + + if style == "pep440": + rendered = render_pep440(pieces) + elif style == "pep440-branch": + rendered = render_pep440_branch(pieces) + elif style == "pep440-pre": + rendered = render_pep440_pre(pieces) + elif style == "pep440-post": + rendered = render_pep440_post(pieces) + elif style == "pep440-post-branch": + rendered = render_pep440_post_branch(pieces) + elif style == "pep440-old": + rendered = render_pep440_old(pieces) + elif style == "git-describe": + rendered = render_git_describe(pieces) + elif style == "git-describe-long": + rendered = render_git_describe_long(pieces) + else: + raise ValueError("unknown style '%s'" % style) + + return {"version": rendered, "full-revisionid": pieces["long"], + "dirty": pieces["dirty"], "error": None, + "date": pieces.get("date")} + + +def get_versions(): + """Get version information or return default if unable to do so.""" + # I am in _version.py, which lives at ROOT/VERSIONFILE_SOURCE. If we have + # __file__, we can work backwards from there to the root. Some + # py2exe/bbfreeze/non-CPython implementations don't do __file__, in which + # case we can only use expanded keywords. + + cfg = get_config() + verbose = cfg.verbose + + try: + return git_versions_from_keywords(get_keywords(), cfg.tag_prefix, + verbose) + except NotThisMethod: + pass + + try: + root = os.path.realpath(__file__) + # versionfile_source is the relative path from the top of the source + # tree (where the .git directory might live) to this file. Invert + # this to find the root from __file__. + for _ in cfg.versionfile_source.split('/'): + root = os.path.dirname(root) + except NameError: + return {"version": "0+unknown", "full-revisionid": None, + "dirty": None, + "error": "unable to find root of source tree", + "date": None} + + try: + pieces = git_pieces_from_vcs(cfg.tag_prefix, root, verbose) + return render(pieces, cfg.style) + except NotThisMethod: + pass + + try: + if cfg.parentdir_prefix: + return versions_from_parentdir(cfg.parentdir_prefix, root, verbose) + except NotThisMethod: + pass + + return {"version": "0+unknown", "full-revisionid": None, + "dirty": None, + "error": "unable to compute version", "date": None} diff --git a/custom-plugins/mkdocs-plugin-tags/tags/plugin.py b/custom-plugins/mkdocs-plugin-tags/tags/plugin.py new file mode 100755 index 0000000..598a6f1 --- /dev/null +++ b/custom-plugins/mkdocs-plugin-tags/tags/plugin.py @@ -0,0 +1,151 @@ +#!/usr/bin/env python +""" +This plugin generates tags file as well as inserts markdown +at the beginning of a file that has tags + +@Adopted from +JL Diaz (c) 2019 +MIT License +""" +from collections import defaultdict +from pathlib import Path +from re import search, DOTALL, MULTILINE +from yaml import load, FullLoader, YAMLError +from jinja2 import Environment, FileSystemLoader +from mkdocs.structure.files import File +from mkdocs.plugins import BasePlugin +from mkdocs.config.config_options import Type +from mkdocs.__main__ import log + +class TagsPlugin(BasePlugin): + """ + Creates "tags.md" file containing a list of the pages grouped by tags + + It uses the info in the YAML metadata of each page, for the pages which + provide a "tags" keyword (whose value is a list of strings) + """ + config_scheme = ( + ('filename', Type(str, default='tags.md')), + ('folder', Type(str, default='aux')), + ('template', Type(str)), + ('css_name', Type(str, default='.button')), + ) + + def __init__(self): + self.metadata = [] + self.tag_dict = None + self.filename = "tags.md" + self.folder = "aux" + self.template = None + self.css_name = ".button" + self.templ = None + + #pylint: disable=unused-argument + def on_page_markdown(self, markdown, page, config, files): + """ + takes markdown, page, config, and files + currently modifies the markdown to add a button to click to get related tag info + tag is customizeable by adding css that keys off the `self.css_name` + """ + + page_url = page.url.split("/") + tags_link = '' + + for i in range(len(page_url) - 1): + tags_link = tags_link + '../' + + tags_link = tags_link + str(self.filename).strip('.md') + + if tags_link[-1] != '/': + tags_link = tags_link + '/' + + if 'tags' in page.meta: + swap_mark = [f"[{x}]({tags_link}#{x.lower()}){{{self.css_name}}}" + for x in page.meta['tags']] + swap_mark.append('\n') + return f'{" ".join(swap_mark)}{markdown}' + return markdown + + def on_config(self, config): + """Load config options""" + self.filename = Path(self.config.get("filename") or self.filename) + self.folder = Path(self.config.get("folder") or self.folder) + self.css_name = self.config.get("css_name") + # Make sure that the tags folder is absolute, and exists + if not self.folder.is_absolute(): + self.folder = Path(config["docs_dir"]) / ".." / self.folder + if not self.folder.exists(): + self.folder.mkdir(parents=True) + + if self.config.get("template"): + self.template = Path(self.config.get("template")) + if self.template is None: + self.template = Path(__file__).parent.joinpath( + "templates" + ).joinpath("tags.md.template") + environment = Environment( + loader=FileSystemLoader(searchpath=str(self.template.parent)) + ) + self.templ = environment.get_template(str(self.template.name)) + + def on_files(self, files, config): + """Load files to check for tags""" + self.metadata = [ + get_metadata(x.src_path, config['docs_dir']) + for x in files if x.src_path.endswith(".md") + ] + # Create new file with tags + self.generate_tags_file() + # New file to add to the build + newfile = File( + path=str(self.filename), + src_dir=str(self.folder), + dest_dir=config["site_dir"], + use_directory_urls=False + ) + files.append(newfile) + + def generate_tags_page(self, data): + """Generate the tags to be populated on the + mkdocs tag page""" + + css_name = self.css_name + + if css_name[0:1] == '.': + css_name = css_name[1:len(css_name)] + return self.templ.render( + tags=sorted(data.items(), key=lambda t: t[0].lower()), + css_name = css_name, + ) + + def generate_tags_file(self): + """Generate a file to be stored on the mkdocs page""" + sorted_meta = sorted(self.metadata, key=lambda e: e.get("year", 5000) if e else 0) + self.tag_dict = defaultdict(list) + for meta in sorted_meta: + if not meta: + continue + if "title" not in meta: + meta["title"] = meta['filename'].split("/")[-1].strip('.md') + tags = meta.get("tags", []) + for tag in tags: + self.tag_dict[tag].append(meta) + + with open(str(self.folder / self.filename), "w", encoding='utf-8') as fname: + fname.write(self.generate_tags_page(self.tag_dict)) + +# Helper functions +def get_metadata(name, path): + """Get the metadata off of a file""" + filename = Path(path) / Path(name) + with filename.open() as fname: + match_string = search(r"\A\s*---\n.*?\n---", fname.read(), flags=DOTALL | MULTILINE) + if match_string: + try: + metadata = match_string.group(0).strip('---') + meta = load(metadata, Loader=FullLoader) + meta.update(filename=name) + return meta + except YAMLError as err: + log.error("Couldn't parse %s yaml due to %s", fname, err) + return None diff --git a/custom-plugins/mkdocs-plugin-tags/tags/templates/tags.md.template b/custom-plugins/mkdocs-plugin-tags/tags/templates/tags.md.template new file mode 100755 index 0000000..3779583 --- /dev/null +++ b/custom-plugins/mkdocs-plugin-tags/tags/templates/tags.md.template @@ -0,0 +1,7 @@ +# Contents grouped by tag +{% for tag, pages in tags %} + +## {{tag}} +{% for page in pages %} +* [{{page.title}}]({{page.filename}}) +{% endfor %}{% endfor %} diff --git a/stylesheets/extra.css b/stylesheets/extra.css new file mode 100644 index 0000000..22ec1c8 --- /dev/null +++ b/stylesheets/extra.css @@ -0,0 +1,121 @@ +html .md-social a[title="DockerHub"] { + color: #0DB7ED; +} + +html .md-social a[title="Facebook"] { + color: #3B5998; + +} + +html .md-social a[title="Github"] { + color: #F5F5F5; +} + +html .md-social a[title="Gitlab"] { + color: #fc6d26; +} + +.docker { + color: #0DB7ED; +} + +.facebook { + color: #3B5998; +} + +.github { + color: #333; +} + +.gitlab { + color: #fc6d26; +} + +.tags { + background-color: #4051B5; + border-radius: 10px; + font-size: 12px; + color: white; + padding: 3px 6px; + text-align: center; + +} + +a.tags:hover { + color: #FFFF00; +} + +.tags:link { + color: white; +} + +.tags:visited { + color: white; +} + + +/* Blog Styles */ +.mdx-author { + display: flex; + font-size: 13.6px; +} +.mdx-author img { + height: 40px; + border-radius: 100%; +} +.mdx-author p:first-child { + flex-shrink: 0; + margin-right: 16px; +} +.mdx-author p > span { + display: block; +} + + +.container{ + width: 100%; +} +.container .row { + width: 95%; + margin: 0 auto; + height: fit-content; +} + +.container .row:after { + content: ""; + display: table; + clear: both; +} +.container .column { + float: left; + width: 50%; + padding-top: 30px; + +} + +.container .column .mdx-author { + padding-left: 30px; +} + +.container .column h2 { + margin: 0px; + text-align: center; +} + +.container .column ul { + margin: 0px; +} + +.container .column h3 { + margin: 0px; +} + +.container .column img { + height: 22px; +} +@media screen and ( max-width: 700px ) { + .container .column { + float: none; + width: 100%; + } +} diff --git a/theme-overrides/.icons/brand/docker.svg b/theme-overrides/.icons/brand/docker.svg new file mode 100755 index 0000000..c4b1319 --- /dev/null +++ b/theme-overrides/.icons/brand/docker.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/theme-overrides/article.html b/theme-overrides/article.html new file mode 100755 index 0000000..789df7b --- /dev/null +++ b/theme-overrides/article.html @@ -0,0 +1,27 @@ +{% extends "base.html" %} + +{% block content %} + + {% if page.meta.type == "blog" %} + + {% elif page.meta.type == "article" %} + + {% endif %} + +

{{ page.title }}

+ {% include "partials/article_metadata.html" %} +
+ {{ page.content }} + + + Published by: {{ config.site_name }}, + + {% if page.meta.copyrightHolder %} +
+ + Copyright {{ page.meta.copyrightHolder }} + + {% endif %} + {% if page.meta.type %}{% endif %} + +{% endblock %} diff --git a/theme-overrides/article_list.html b/theme-overrides/article_list.html new file mode 100755 index 0000000..dbe7cfc --- /dev/null +++ b/theme-overrides/article_list.html @@ -0,0 +1,38 @@ +{% extends "base.html" %} + +{% block content %} + {{ page.content }} + {% set article_posts = [] %} + {% for page in nav.pages %} + {% if page.url.startswith(config.extra.blog.dir) and page.meta.date is defined %} + + {{ article_posts.append( page ) or "" }} + {% endif %} + {% endfor %} + + {% for page in (article_posts|sort(attribute="meta.date", reverse=True))[:config.extra.blog.list_length] %} + {% if page.meta.type == "blog" %} + + {% elif page.meta.type == "article" %} + + {% endif %} +

+
+ {% include "partials/article_metadata.html" %} +

+ {{ page.meta.description }} +

+ + {% if config.extra.blog.extended_preview %} + + + {% include ".icons/octicons/arrow-right-24.svg" %} + + Continue reading +
+ + {% endif %} + {% if page.meta.type %}{% endif %} + {% endfor %} + +{% endblock %} diff --git a/theme-overrides/home.html b/theme-overrides/home.html new file mode 100755 index 0000000..127f090 --- /dev/null +++ b/theme-overrides/home.html @@ -0,0 +1,68 @@ +{% extends "base.html" %} + +{% block content %} +
+ {{ page.content }} + {% set article_posts = [] %} + {% for page in nav.pages %} + {% if page.url.startswith(config.extra.blog.dir) and page.meta.date is defined %} + + {{ article_posts.append( page ) or "" }} + {% endif %} + {% endfor %} + +
+
+
+ +
    + {% for page in (article_posts|sort(attribute="meta.date", reverse=True))[:config.extra.blog.list_length] %} + {% if page.meta.type == "blog" %} +
  • + {% elif page.meta.type == "article" %} +
  • + {% else %} +
  • + {% endif %} +

    +

    + +

    +
    • + {% endfor %} +
+
+
+

Quick Links

+ +
+
+
+ +
+{% endblock %} diff --git a/theme-overrides/manual.html b/theme-overrides/manual.html new file mode 100755 index 0000000..1a73d65 --- /dev/null +++ b/theme-overrides/manual.html @@ -0,0 +1,63 @@ +{% extends "base.html" %} + +{% block content %} + +{% if page.edit_url %} + + {% include ".icons/material/pencil.svg" %} + +{% endif %} + + + + + +

{{ page.title }}

+ +
+ + + {{ page.content }} + + + + + + +
+

About:

+

This page forms part of our Operations Manual.

+

+

Page Metadata
+ Version: ToDo: place files short git commit here
+ Date Created: {{ page.meta.date.strftime("%Y-%m-%d") }}
+ {% if page.meta.git_revision_date_localized %}Date Edited: {{ page.meta.git_revision_date_localized.replace("\n", "").replace("\r", "") }}
{% endif %} +

+ +
Contribution:
+

Would You like to contribute to our Operations Manual? You can assist in the following ways:

+ +

 

+

ToDo: Add the page list of contributors

+ +
+ + + +{% endblock %} diff --git a/theme-overrides/partials/article_extended_preview.html b/theme-overrides/partials/article_extended_preview.html new file mode 100755 index 0000000..085d23b --- /dev/null +++ b/theme-overrides/partials/article_extended_preview.html @@ -0,0 +1,7 @@ + + + {% include ".icons/octicons/arrow-right-24.svg" %} + + Continue reading +
+ diff --git a/theme-overrides/partials/article_metadata.html b/theme-overrides/partials/article_metadata.html new file mode 100755 index 0000000..e11a471 --- /dev/null +++ b/theme-overrides/partials/article_metadata.html @@ -0,0 +1,32 @@ + diff --git a/theme-overrides/partials/article_social.html b/theme-overrides/partials/article_social.html new file mode 100755 index 0000000..cad4111 --- /dev/null +++ b/theme-overrides/partials/article_social.html @@ -0,0 +1,17 @@ +{% if config.extra.social %} + {% set ns = namespace() %} + {% for social in config.extra.social %} + {% set title = social.name %} + {% if not title and "//" in social.link %} + {% set _,url = social.link.split("//") %} + {% set title = url.split("/")[0] %} + {% endif %} + {% if ns.line_break is defined %} + {{ ns.line_break }} + {% endif %} + + {% include ".icons/" ~ social.icon ~ ".svg" %} + + {% set ns.line_break = " · " %} + {% endfor %} +{% endif %} \ No newline at end of file diff --git a/theme-overrides/partials/footer.html b/theme-overrides/partials/footer.html new file mode 100755 index 0000000..caa78b0 --- /dev/null +++ b/theme-overrides/partials/footer.html @@ -0,0 +1,14 @@ +{#- + This file was automatically generated - do not edit +-#} +
+ +
+
+ {% include "partials/copyright.html" %} + {% if config.extra.social %} + {% include "partials/social.html" %} + {% endif %} +
+
+
diff --git a/theme-overrides/sitemap.xml b/theme-overrides/sitemap.xml new file mode 100755 index 0000000..81bc017 --- /dev/null +++ b/theme-overrides/sitemap.xml @@ -0,0 +1,12 @@ + + +{%- for file in pages -%} + {% if not file.page.is_link %} + + {% if file.page.canonical_url %}{{ file.page.canonical_url|e }}{% else %}{{ file.page.abs_url|e }}{% endif %} + {% if file.page.meta.git_revision_date_localized %}{{ file.page.meta.git_revision_date_localized.replace("\n", "").replace("\r", "").replace('', '').replace('','') }}{% endif %} + weekly + + {%- endif -%} +{% endfor %} + \ No newline at end of file