diff --git a/templates/docs/_data/plugins.py b/templates/docs/_data/plugins.py new file mode 100644 index 0000000000000000000000000000000000000000..f2a9800b7e8a906ef88aed257382c2d56c87cc6d --- /dev/null +++ b/templates/docs/_data/plugins.py @@ -0,0 +1,673 @@ +#!/usr/bin/env python3 +""" +Set of method for mkdocs-macros which also update nav entry to dynamically +support subrepo with mkdocs monorepo plugin. +""" + +# pylint: disable=R0801 + +# JSON encoder and decoder +# https://docs.python.org/3/library/json.html +import json + +# Logging facility +# https://docs.python.org/3/library/logging.html +import logging + +# Miscellaneous operating system interfaces +# https://docs.python.org/3/library/os.html +import os + +# Regular expression operations +# https://docs.python.org/3/library/re.html +import re + +# High-level file operations +# https://docs.python.org/3/library/shutil.html +import shutil + +# System-specific parameters and functions +# https://docs.python.org/3/library/sys.html +import sys + +# Time access and conversions +# https://docs.python.org/3/library/time.html +import time + +# Python Git Library +# https://pypi.org/project/GitPython/ +import git + +# YAML parser and emitter for Python +# https://pypi.org/project/PyYAML/ +import yaml + +# Python lib/cli for JSON/YAML schema validation +# https://pypi.org/project/pykwalify/ +from pykwalify.core import Core as yamlschema + +# pylint: disable=W0105 +# - W0105: String statement has no effect +LOG = logging.getLogger(__name__) +"""The logger facilty""" +ERR_CLR = "\033[31m" +"""String coloring error output in red""" +INFO_CLR = "\033[32m" +"""String coloring error output in green""" +RESET_CLR = "\033[0m" +"""String reseting coloring output""" + + +def add_internal_to_nav( + env: dict, + nav: dict, + repo_dict: dict, + repo_parent: list, + nav_parent: list = None, +) -> None: + """ + @rdeville TODO + """ + if nav_parent: + for i_nav in nav: + if nav_parent[0] in i_nav: + for i_key in i_nav: + add_internal_to_nav( + env, + i_nav[i_key], + repo_dict, + repo_parent, + nav_parent[1:], + ) + else: + mkdocs_path = env.project_dir + for i_parent in repo_parent: + mkdocs_path = os.path.join(mkdocs_path, i_parent) + mkdocs_path = os.path.join(mkdocs_path, repo_dict["name"]) + if "subpath" in repo_dict: + mkdocs_path = os.path.join(mkdocs_path, repo_dict["subpath"]) + mkdocs_path = os.path.join(mkdocs_path, "mkdocs.yml") + nav.append({repo_dict["nav_entry"]: f"!include {mkdocs_path}"}) + + +def add_external_to_nav( + env: dict, nav: dict, repo_dict: dict, repo_parent: list, nav_parent: list +) -> None: + """ + @rdeville TODO + """ + if nav_parent: + for i_nav in nav: + if nav_parent[0] in i_nav: + for i_key in i_nav: + add_external_to_nav( + env, + i_nav[i_key], + repo_dict, + repo_parent, + nav_parent[1:], + ) + else: + nav.append({repo_dict["nav_entry"]: repo_dict["online_url"]}) + + +def add_nav_entry(nav: list, nav_parent: list = None) -> None: + """ + @rdeville TODO + """ + entry = dict() + + for i_nav in nav: + if nav_parent[0] in i_nav: + entry = i_nav + + if not entry: + entry = {nav_parent[0]: []} + nav.append(entry) + + if len(nav_parent[1:]) == 0: + return + add_nav_entry(entry[nav_parent[0]], nav_parent[1:]) + + +def update_nav( + env: dict, + repo_dict: dict, + repo_parent: list = None, + nav_parent: list = None, + first_iteration=False, +) -> None: + """ + @rdeville TODO + """ + for i_key in repo_dict: + if not nav_parent or first_iteration: + nav_parent = list() + + if not repo_parent or first_iteration: + repo_parent = list() + + if i_key == "nav_entry": + nav_parent.append(repo_dict["nav_entry"]) + elif i_key == "internal": + for i_repo in repo_dict["internal"]: + add_nav_entry(env.conf["nav"], nav_parent) + add_internal_to_nav( + env, env.conf["nav"], i_repo, repo_parent, nav_parent + ) + elif i_key == "external": + for i_repo in repo_dict["external"]: + add_nav_entry(env.conf["nav"], nav_parent) + add_external_to_nav( + env, env.conf["nav"], i_repo, repo_parent, nav_parent + ) + else: + repo_parent.append(i_key) + update_nav(env, repo_dict[i_key], repo_parent, nav_parent) + + +def get_repo_slug(env, git_repo): + """Compute the slug of the current repo and ensure repo dict is defined + + Compute the slug of the current repo based on the origin remote. If no remo, + then will use the folder name. + Then ensure the repo dictionary is defined in `docs/_data/`. If not, print + an error and exit. + + Arguments: + env: Mkdocs macro plugin environment dictionary. + git_repo: Git python object of the current repo. + """ + if git_repo.remotes: + repo_slug = ( + git_repo.remotes.origin.url.rsplit("/")[-1] + .split(".git")[0] + .replace(".", "_") + ) + else: + repo_slug = os.path.basename(env.project_dir) + + if repo_slug not in env.variables: + LOG.error( + "%s[macros] - Dictionnary %s is not defined.%s", + ERR_CLR, + repo_slug, + RESET_CLR, + ) + LOG.error( + "%s[macros] - Ensure you copy docs/_data/templates/repo.tpl.yaml " + "to docs/_data/%s.yaml.%s", + ERR_CLR, + repo_slug, + RESET_CLR, + ) + LOG.error( + "%s[macros] - And you setup dictionary %s in docs/_data/%s.yaml.%s", + ERR_CLR, + repo_slug, + repo_slug, + RESET_CLR, + ) + sys.exit(1) + + env.variables["git"]["repo_slug"] = repo_slug + return repo_slug + + +def set_site_name(env, repo_slug): + """Update content of the `site_name` key in mkdocs.yml + + If `site_name` key is not defined in `mkdocs.yml` then look to + `docs/_data/vars.yml`, if defined, else look to the the current repo + dictionary to set value of `site_name`. + + Arguments: + env: Mkdocs macro plugin environment dictionary. + repo_slug: Repo slug or name of the repo folder. + """ + if "site_name" not in env.conf or not env.conf["site_name"]: + if "site_name" in env.variables: + env.conf["site_name"] = env.variables["site_name"] + else: + env.conf["site_name"] = env.variables[repo_slug]["name"] + + +def set_site_desc(env, repo_slug): + """Update content of the `site_desc` key in mkdocs.yml + + If `site_desc` key is not defined in `mkdocs.yml` then look to + `docs/_data/vars.yml`, if defined, else look to the the current repo + dictionary to set value of `site_desc`. + + Arguments: + env: Mkdocs macro plugin environment dictionary. + repo_slug: Repo slug or name of the repo folder. + """ + if "site_desc" not in env.conf: + if "site_desc" in env.variables: + env.conf["site_desc"] = env.variables["site_desc"] + else: + env.conf["site_desc"] = env.variables[repo_slug]["desc"] + + +def set_site_url(env, repo_slug): + """Update content of the `site_url` key in mkdocs.yml + + If `site_url` key is not defined in `mkdocs.yml` then look to + `docs/_data/vars.yml`, if defined, else build value from `site_base_url` and + the current repo dictionary. + + Arguments: + env: Mkdocs macro plugin environment dictionary. + repo_slug: Repo slug or name of the repo folder. + """ + if "site_url" not in env.conf: + if "site_url" in env.variables: + env.conf["site_url"] = env.variables["site_url"] + elif "site_base_url" in env.variables: + site_url = ( + env.variables["site_base_url"] + + env.variables[repo_slug]["url_slug_with_namespace"] + ) + env.conf["site_url"] = site_url + + +def set_copyright(env, git_repo): + """Update content of the `copyright` key in mkdocs.yml + + If `copyright` key is not defined in `mkdocs.yml` but is defined in + `docs/_data/vars.yml`, this override the content of the default `copyright` + key in `mkdocs.yml` with date based on the first commit of the repo. + + Arguments: + env: Mkdocs macro plugin environment dictionary. + git_repo: Git python object of the current repo. + """ + if ( + "copyright" not in env.conf or not env.conf["copyright"] + ) and "copyright" in env.variables: + if git_repo.branches and git_repo.branches.master: + first_date = git_repo.commit( + git_repo.branches.master.log()[0].newhexsha + ).committed_date + first_year = time.strftime("%Y", time.gmtime(first_date)) + else: + first_year = time.strftime("%Y", time.localtime()) + curr_year = time.strftime("%Y", time.localtime()) + + env.conf["copyright"] = "Copyright © {} - {} {}".format( + first_year, curr_year, env.variables["copyright"] + ) + + +def set_repo_name(env, repo_slug): + """Update content of the `repo_url` key in mkdocs.yml + + If `repo_url` key is defined in `docs/_data/vars.yml`, this override the + content of the default `repo_url` key in `mkdocs.yml`. Else, update the + repo_url based on the value of `git_platform` dictionary and the dictionary + corresponding of the repo. + + Arguments: + env: Mkdocs macro plugin environment dictionary. + repo_slug: Repo slug or name of the repo folder. + """ + + if "repo_name" not in env.conf or not env.conf["repo_name"]: + if "name" in env.variables[repo_slug]: + if env.variables[repo_slug]["name"] == "!!git_platform": + env.conf["repo_name"] = env.variables["git_platform"]["name"] + else: + env.conf["repo_name"] = env.variables[repo_slug]["name"] + + +def set_repo_url(env, repo_slug): + """Update content of the `repo_url` key in mkdocs.yml + + If `repo_url` key is defined in `docs/_data/vars.yml`, this override the + content of the default `repo_url` key in `mkdocs.yml`. Else, update the + repo_url based on the value of `git_platform` dictionary and the dictionary + corresponding of the repo. + + Arguments: + env: Mkdocs macro plugin environment dictionary. + repo_slug: Repo slug or name of the repo folder. + """ + if "repo_url" not in env.conf or not env.conf["repo_url"]: + if "repo_url" in env.variables: + env.conf["repo_url"] = env.variables["repo_url"] + elif "repo_url" in env.conf: + env.conf["repo_url"] = "{}{}".format( + env.variables["git_platform"]["url"], + env.variables[repo_slug]["git_slug_with_namespace"], + ) + + +def update_theme(env, repo_slug): + """Update content of the `theme` key in mkdocs.yml + + If `theme` key is defined in `docs/_data/vars.yml`, this override the + content of the default `theme` key in `mkdocs.yml`. + + Arguments: + env: Mkdocs macro plugin environment dictionary. + repo_slug: Repo slug or name of the repo folder. + """ + if "theme" in env.variables: + for i_key in env.variables["theme"]: + env.conf["theme"][i_key] = env.variables["theme"][i_key] + + if "logo" not in env.conf["theme"] or not env.conf["theme"]["logo"]: + if "logo" in env.variables[repo_slug]: + env.conf["theme"]["logo"] = env.variables[repo_slug]["logo"] + else: + env.conf["theme"]["logo"] = os.path.join( + "assets", "img", "meta", f"{repo_slug}_logo.png" + ) + + if not env.conf["theme"]["icon"]: + env.conf["theme"]["icon"] = {} + + if "icon" not in env.conf["theme"] or not env.conf["theme"]["icon"]: + env.conf["theme"]["icon"]["repo"] = env.variables["git_platform"][ + "icon" + ] + + if "favicon" not in env.conf["theme"] or not env.conf["theme"]["favicon"]: + if "favicon" in env.variables[repo_slug]: + env.conf["theme"]["favicon"] = env.variables[repo_slug]["favicon"] + elif "logo" in env.variables[repo_slug]: + env.conf["theme"]["favicon"] = env.variables[repo_slug]["logo"] + else: + env.conf["theme"]["favicon"] = os.path.join( + "assets", "img", "meta", f"{repo_slug}_logo.png" + ) + + +def set_config(env: dict) -> None: + """Dynamically update mkdocs configuration + + Based on the repo slug (or folder name) load variables in + `docs/_data/vars.yml` and update content of mkdocs.yml accordingly. + + Especially, if `docs/_data/subrepo.yaml` exists and define valid subrepod, + dynamically add these subrepo to the `nav` key of the mkdocs.yml + configuration. + + Arguments: + env: Mkdocs macro plugin environment dictionary. + """ + + git_repo = git.Repo(search_parent_directories=True) + repo_slug = get_repo_slug(env, git_repo) + + set_site_name(env, repo_slug) + set_site_desc(env, repo_slug) + set_site_url(env, repo_slug) + set_copyright(env, git_repo) + set_repo_name(env, repo_slug) + set_repo_url(env, repo_slug) + update_theme(env, repo_slug) + + if "subrepo" in env.variables: + if ( + env.variables["internal_subdoc"] + and "monorepo" in env.conf["plugins"] + ): + env.conf["plugins"].pop("monorepo") + else: + update_nav(env, env.variables["subrepo"], first_iteration=True) + + +def load_yaml_file(path: str, filename: str) -> None: + """Ensure a YAML file is valid again a schema and return its content + + Depending on the name of the YAML file, compare its content to a schema to + validate its content. If content is not valid, an error will be raised. + Otherwise, its content will be returned. + + Arguments: + path: Base path where YAML files are. + filename: Name of the YAML file to load. + """ + source_file = os.path.join(path, filename) + schema_file = os.path.join(path, "schema") + data_type = "" + + if filename in ("subrepo.yaml", "subrepo.yml"): + schema_file = os.path.join(schema_file, "subrepo.schema.yaml") + elif filename in ("vars.yaml", "vars.yml"): + schema_file = os.path.join(schema_file, "vars.schema.yaml") + else: + schema_file = os.path.join(schema_file, "repo.schema.yaml") + data_type = "repo" + + schema = yamlschema(source_file=source_file, schema_files=[schema_file]) + schema.validate(raise_exception=True) + return schema.source, data_type + + +def update_subrepo_logo_src(env:dict,curr_repo:dict,repo_name:str,subrepo_dict:dict, path:str,external:bool) -> None: + logo_subpath = "" + src_subpath = "" + if external: + logo_subpath = os.path.join(subrepo_dict["online_url"]) + + src_subpath = os.path.join(path.replace(f"{env.project_dir}/",""),repo_name) + + if "logo" not in curr_repo: + curr_repo["logo"] = os.path.join(logo_subpath, "assets", "img", "meta",f"{repo_name}_logo.png") + if "src_path" in curr_repo: + for i_src in curr_repo["src_path"]: + i_src = os.path.join(src_subpath, i_src) + env.conf["plugins"]["mkdocstrings"].config.data["handlers"][ + "python" + ]["setup_commands"].append(f"sys.path.append('{i_src}')") + + +def update_subrepo_info(env: dict, subrepo_list: dict, path: str, external:bool = False) -> dict: + """ + @rdeville TODO + """ + return_dict = dict() + for i_repo in subrepo_list: + subrepo_root = os.path.join(path, i_repo["name"]) + + if os.path.isdir(subrepo_root): + print( + f"{INFO_CLR}INFO [macros] - Pulling repo {i_repo['name']}{RESET_CLR}" + ) + git_subrepo = git.Repo(subrepo_root) + git_subrepo.remotes.origin.pull() + else: + print( + f"{INFO_CLR}INFO [macros] - Cloning repo {i_repo['name']}{RESET_CLR}" + ) + git.Repo.clone_from(i_repo["git_url"], subrepo_root) + + if "subpath" in i_repo: + data_dir = os.path.join( + subrepo_root, i_repo["subpath"], "docs", "_data" + ) + else: + data_dir = os.path.join(subrepo_root, "docs", "_data") + + data_file = os.path.join(data_dir, f"{i_repo['name']}.yaml") + data, _ = load_yaml_file(data_dir, data_file) + for i_repo_info in data: + curr_repo = data[i_repo_info] + update_subrepo_logo_src(env,curr_repo,i_repo_info,i_repo,path,external) + return_dict.update(data) + return return_dict + + +def update_subrepo(env: dict, subrepo_dict: dict, path: str, external:bool) -> dict: + """ + @rdeville TODO + """ + return_dict = dict() + for i_key in subrepo_dict: + if isinstance(subrepo_dict[i_key], list): + if i_key == "external": + external = True + elif i_key == "internal": + env.variables["internal_subdoc"] = True + return_dict.update( + update_subrepo_info(env, subrepo_dict[i_key], path,external) + ) + elif i_key not in ["nav_entry"]: + return_dict.update( + update_subrepo( + env, subrepo_dict[i_key], os.path.join(path, i_key),external + ) + ) + return return_dict + + +def update_logo_src_repo(env:dict,curr_repo:dict,repo_name:str,path:str=None) -> None: + subpath = "" + if path: + subpath = os.path.join(path.replace(env.project_dir,""),repo_name) + + if "logo" not in curr_repo: + curr_repo["logo"] = os.path.join(subpath, "assets", "img", "meta",f"{repo_name}_logo.png") + if "src_path" in curr_repo: + for i_src in curr_repo["src_path"]: + i_src = os.path.join(subpath, i_src) + env.conf["plugins"]["mkdocstrings"].config.data["handlers"][ + "python" + ]["setup_commands"].append(f"sys.path.append('{i_src}')") + + + +def load_var_file(env: dict) -> None: + """Load variables files in docs/_data/ and variable of subrepo + + Load every yaml files in docs/_data/, if one of the file define a `subrepo` + key, load every variables associated to subrepo. + + Arguments: + env: Mkdocs macro plugin environment dictionary. + """ + var_dir = os.path.join(env.project_dir, "docs", "_data") + + for i_file in os.listdir(var_dir): + if i_file.endswith((".yml", ".yaml")): + data, data_type = load_yaml_file(var_dir, i_file) + for i_key in data: + if data_type == "repo": + update_logo_src_repo(env,data[i_key],i_key) + env.variables[i_key] = data[i_key] + + +def update_version(env: dict) -> None: + """Update docs/versions.json if last commit has a tag + + Arguments: + env: Mkdocs macro plugin environment dictionary. + """ + if ( + "version" not in env.variables + or "provider" not in env.variables["version"] + or env.variables["version"]["provider"] != "mike" + ): + return + git_repo = git.Repo(search_parent_directories=True) + mike_version = list() + last_major = 0 + last_minor = 0 + last_patch = 0 + for i_tag in git_repo.tags: + i_tag = yaml.dump(i_tag.path) + i_tag = re.sub(".*v", "", i_tag).split(".") + major = int(i_tag[0]) + minor = int(i_tag[1]) + patch = int(i_tag[2]) + if major > last_major: + mike_version.append( + { + "version": "{}.{}".format(last_major, last_minor), + "title": "{}.{}.{}".format( + last_major, last_minor, last_patch + ), + "aliases": [], + } + ) + last_major = major + last_minor = 0 + if minor > last_minor: + mike_version.append( + { + "version": "{}.{}".format(last_major, last_minor), + "title": "{}.{}.{}".format( + last_major, last_minor, last_patch + ), + "aliases": [], + } + ) + last_minor = minor + last_patch = 0 + if patch > last_patch: + last_patch = patch + mike_version.append( + { + "version": "{}.{}".format(last_major, last_minor), + "title": "{}.{}.{}".format(last_major, last_minor, last_patch), + "aliases": ["latest"], + } + ) + mike_version.reverse() + with open( + os.path.join(env.project_dir, "docs", "versions.json"), "w" + ) as version_file: + json.dump(mike_version, version_file, indent=2) + + +def define_env(env: dict) -> None: + # pylint: disable=C0301 + # - C0301: Line to long + """ + This is the hook for defining variables, macros and filters + + - variables: the dictionary that contains the environment variables + - macro: a decorator function, to declare a macro. + + See + [https://mkdocs-macros-plugin.readthedocs.io/en/latest/](https://mkdocs-macros-plugin.readthedocs.io/en/latest/) + + Arguments: + env: Mkdocs macro plugin environment dictionary. + """ + + load_var_file(env) + + if "subrepo" in env.variables: + env.variables["internal_subdoc"] = False + env.variables.update( + update_subrepo(env, env.variables["subrepo"], env.project_dir, False) + ) + + set_config(env) + + update_version(env) + + @env.macro + # pylint: disable=W0612 + # - W0612: Unused variable (unused-variable) + def subs(var: str) -> dict: + """Return the content of the dictionary defined by var""" + return env.variables[var] + + @env.macro + # pylint: disable=W0612 + # - W0612: Unused variable (unused-variable) + def get_repo() -> dict: + """Return the content of the dictionary of the current repo""" + git_repo = git.Repo(search_parent_directories=True) + return env.variables[get_repo_slug(env, git_repo)] + + +# ----------------------------------------------------------------------------- +# VIM MODELINE +# vim: fdm=indent +# ----------------------------------------------------------------------------- diff --git a/templates/docs/_data/schema/repo.schema.yaml b/templates/docs/_data/schema/repo.schema.yaml new file mode 100644 index 0000000000000000000000000000000000000000..e1eb877c39c547367cda6fc01da1387fd3783758 --- /dev/null +++ b/templates/docs/_data/schema/repo.schema.yaml @@ -0,0 +1,42 @@ +# Schema to validate yaml files describing repo information +type: map +mapping: + regex;([a-zA-z0-9_-]+): + type: map + required: true + example: >- + Provide a dictionnary which main key is compose of alphanumerical values + with `-` and `_`. + mapping: + regex;(name|git_slug_with_namespace|desc): + type: str + required: true + example: >- + Key `name`, `git_slug_with_namespace` and `desc` are string and are + required. + regex;(git_name_with_namespace|logo): + type: str + required: false + example: >- + Key `git_name_with_namespace` and `logo` are string and are not + required. + src_path: + type: seq + required: false + example: >- + Key `src_path` is a list of string and is not required. + sequence: + - type: str + maintainers: + type: seq + required: true + example: >- + Key `src_path` is a list of dictionary and is required. + sequence: + - type: map + mapping: + regex;(name|mail): + type: str + required: true + example: >- + Key `name` and `mail` are string and are required. diff --git a/templates/docs/_data/schema/subrepo.schema.yaml b/templates/docs/_data/schema/subrepo.schema.yaml new file mode 100644 index 0000000000000000000000000000000000000000..2b7662f0c8130f9b76d9b8f1111d3e9b7d9f6f54 --- /dev/null +++ b/templates/docs/_data/schema/subrepo.schema.yaml @@ -0,0 +1,99 @@ +# Schema to validate subrepo.yml +schema;subrepo_map: + type: map + required: true + example: >- + Provide a dictionary which main key is compose of alphanumerical values + with `-` and `_`. + mapping: + nav_entry: + type: str + required: false + example: >- + Key `nav_entry` is a str corresponding to the entry in the `nav` key. + internal: + type: seq + required: false + example: >- + Key `internal` is a list of dictionary information. + sequence: + - type: map + required: true + example: >- + Dict storing information about the subrepo which will be + cloned/pulled. + mapping: + name: + type: str + required: true + example: >- + Key `name` is a str, the foler where the subrepo should be + cloned/pulled. + git_url: + type: str + required: true + example: >- + Key `git_url` is a str validate again a regexp which hold the SSH or + HTTP URL of the repo to be cloned/pulled. + nav_entry: + type: str + required: true + example: >- + Key `nav_entry` is a str corresponding to the entry in the `nav` + key. + subpath: + type: str + required: false + example: >- + Key `subpath` is a str pointing to the path in the subrepo where + there is a file `mkdocs.yaml` and folder `docs`. + external: + type: seq + required: false + example: >- + Key `internal` is a list of dictionary information. + sequence: + - type: map + required: true + example: >- + Dict storing information about the subrepo which will be + cloned/pulled. + mapping: + name: + type: str + required: true + example: >- + Key `name` is a str, the foler where the subrepo should be + cloned/pulled. + git_url: + type: str + required: true + example: >- + Key `git_url` is a str validate again a regexp which hold the SSH or + HTTP URL of the repo to be cloned/pulled. + nav_entry: + type: str + required: true + example: >- + Key `nav_entry` is a str corresponding to the entry in the `nav` + key. + subpath: + type: str + required: false + example: >- + Key `subpath` is a str pointing to the path in the subrepo where + there is a file `mkdocs.yaml` and folder `docs`. + online_url: + type: str + required: true + example: >- + Key `online_url` is a str pointing to online URL of the subrepo + documentation. Can be a full URL or a path relative to the root + regex;([a-zA-z0-9_-]+): + include: subrepo_map + +type: map +required: true +mapping: + subrepo: + include: subrepo_map diff --git a/templates/docs/_data/schema/vars.schema.yaml b/templates/docs/_data/schema/vars.schema.yaml new file mode 100644 index 0000000000000000000000000000000000000000..689314f8187b4cc1b0f107776cd56fcf2dbb409e --- /dev/null +++ b/templates/docs/_data/schema/vars.schema.yaml @@ -0,0 +1,87 @@ +# Schema to validate vars.yml +type: map +mapping: +# Mkdocs.yaml Section Schema +# --------------------------------------------------------------------------- + regex;(site_name|site_desc|copyright|repo_name): + type: str + required: false + example: >- + Key `site_name`, `site_desc`, `site_url`, `copyright` or `repo_name` are + string and are optional + regex;(site_url|repo_url|site_base_url): + type: url + required: false + example: >- + Key `site_name`, `site_desc`, `site_url`, `copyright` or `repo_name` are + valid URL and are optional + theme: + type: map + required: false + example: Dictionary key `theme` is optional + mapping: + regex;(name|custom_dir|language|logo|favicon): + type: str + required: false + example: >- + Key `name`, `custom_dir`, `language`, `logo` or `favicon` are string + and are optional + regex;(include_search_page|search_index_only): + type: bool + required: false + example: >- + Key `include_search_page` and `search_index_only` are boolean and + are optional + features: + type: seq + required: false + example: List key `features` is composed of string and is optional + sequence: + - type: str + palette: + type: map + required: false + example: Dictionary key `palette` is optional + mapping: + regex;(scheme|primary|accent): + type: str + required: false + example: >- + Key `scheme`, `primary` or `accent` are string and are optional + font: + type: map + required: false + example: Dictionary key `palette` is optional + mapping: + regex;(text|code): + type: str + required: false + example: >- + Key `text` or `code` are string and are optional + icon: + type: map + required: false + example: Dictionary key `icon` is optional + mapping: + regex;(logo|repo): + type: str + required: false + example: >- + Key `logo` or `repo` are string and are optional +# Git platform section schema +# --------------------------------------------------------------------------- + git_platform: + type: map + required: true + example: Dictionary key `git_platform` is required + mapping: + regex;(logo|icon|name): + type: str + required: true + example: >- + Key `logo`, `icon` and `name are string and are required` + url: + type: url + required: true + example: >- + Key `url` is a URL and is required \ No newline at end of file diff --git a/templates/docs/_data/template/repo.tpl.yaml b/templates/docs/_data/template/repo.tpl.yaml new file mode 100644 index 0000000000000000000000000000000000000000..e86ea591a9789ec0a7728e068c997aa9f079dc57 --- /dev/null +++ b/templates/docs/_data/template/repo.tpl.yaml @@ -0,0 +1,45 @@ +# Repo information +# =========================================================================== +# First key MUST be the "slug" of the repo based on the remote, i.e. if remote +# is git@git.domain.tld:username/repo_name.git, then the key will be +# `repo_name`. +repo_name: + + # An explicit name for the repo that will be shown on the documentation + # page. + name: "My Repo Name" + + # (OPTIONATL) An extension of the explicit name with the namespace in which + # the repo is. For instance, using above remote, the entry will be + # `Username / Repo Name`. + # This entry is not used in the configuration of mkdocs. + git_name_with_namespace: "Namespace / My Repo Name" + + # The complete path of the repo from the git_platform["url"]. For instance, + # using, above remote, the entry will be `username/repo_name.git` + git_slug_with_namespace: "namespace/repo_name" + + # If the repo documentation is part of a bigger repo, then provide the + # path of the rendered documentation. If the documentation is not part of + # another repo, leave it empty. + url_slug_with_namespace: "subpath_for_url_renderin/repo_slug" + + # (OPTIONAL) Path, relative to `docs_dir` mkdocs config, to the logo of the + # repo. If not specified, path will automatically be set to + # `assets/img/meta/reop_name_logo.png` + #logo: "assets/img/meta/repo_template_logo.png" + # Description of the repo, will be used to setup the mkdocs description. + desc: >- + Repo description with markdown support + + # (OPTIONAL) If you plan to use `mkdocstring` plugins to render python + # source code, you will need to provide the path where your source files + # are relative to the root of the repo. + src_path: + - "src" + + # List of informations about the main maintainers that will be automatically + # added to the license file in `docs/about/license.md` + maintainers: + - name: "Firstname Lastname" + mail: "mail@domain.tld" \ No newline at end of file diff --git a/templates/docs/_data/template/subrepo.tpl.yaml b/templates/docs/_data/template/subrepo.tpl.yaml new file mode 100644 index 0000000000000000000000000000000000000000..d23a85e17a4e7639e7b653ed7a806534431be4fb --- /dev/null +++ b/templates/docs/_data/template/subrepo.tpl.yaml @@ -0,0 +1,73 @@ +# Subrepo Information +# --------------------------------------------------------------------------- +# Dictionnary storing location of subrepo to be included in the main repo +# documentation + +# The main key MUST be `subrepo`. +subrepo: + # You can provide multiple nesting level of dictionary defining path to + # the subrepo to include to the main repo documentation such as: + # # Name of the directory + # ``` + # dir_name: + # # Corresponding EXISTING entry in the `nav` key of mkdocs. + # nav_entry: "Nav Entry" + # # List of subdirectory from `dir_name` which are repos with + # # mkdocs documentation for which only link to the repo documentation + # # will be provided. + # external: + # # i.e. There is a file `mkdocs.yaml` in + # # `dir_name/subrepo_1/mkdocs.yaml` and + # # `dir_name/subrepo_1/docs/_data/subrepo_1.yaml` + # - name: subrepo_1 + # # SSH or HTTP link to the online subrepo_1 + # git_url: git@domain.tld:namesapce/subrepo_1 + # # List of subdirectory from `dir_name` which are repos with + # # mkdocs documentation which will be included in the documentation. + # external: + # # i.e. There is a file `mkdocs.yaml` in + # # `dir_name/subrepo_2/mkdocs.yaml` and + # # `dir_name/subrepo_2/docs/_data/subrepo_2.yaml` + # - name: subrepo_2 + # # SSH or HTTP link to the online subrepo_2 + # git_url: git@domain.tld:namesapce/subrepo_2 + # # Another sub dir_name which also old subrepos + # subdir_name: + # nav_entry: "Sub Nav Entry" + # [...] + # # Another sub dir_name which also old subrepos + # another_dir_name: + # nav_entry: "Another Nav Entry" + # [...] + # ``` + + # Below is a short example used for the rendering of + # `docs.romaindeville.fr` + my_dotfiles: + nav_entry: My Dotfiles + internal: + - name: myrepos + nav_entry: MyRepos Template + git_url: git@framagit.org:rdeville.private/my_dotfiles/myrepos.git + my_program: + nav_entry: My Programs + external: + - name: direnv_template + nav_entry: Direnv Template + git_url: git@framagit.org:rdeville.private/my_programs/direnv_template.git + - name: mkdocs_template + nav_entry: Mkdocs Template + git_url: git@framagit.org:rdeville.private/my_programs/mkdocs_template.git + + # This example will allow to add the following content to the `nav` key + # ``` + # nav: + # [...] + # - My Dotfiles: + # # Monorepo will include following mkdocs.yaml + # - MyRepos Template: !include my_dotfiles/myrepos/mkdocs.yaml + # - My Programs: + # # A link will be provided to the external documentation + # - Direnv Template: /my_program/direnv_template/ + # - Mkdocs Template: /my_program/mkdocs_template/ + # ``` diff --git a/templates/docs/_data/template/vars.tpl.yaml b/templates/docs/_data/template/vars.tpl.yaml new file mode 100644 index 0000000000000000000000000000000000000000..557fd5582a11ac528862b35017c2119768cc5b78 --- /dev/null +++ b/templates/docs/_data/template/vars.tpl.yaml @@ -0,0 +1,91 @@ +# Extra Data Information & Customization +# =========================================================================== +# Dictionnary storing variables to be used as "Jinja2" variables within +# markdown files and _data/plugins.py + +# Mkdocs.yaml +# --------------------------------------------------------------------------- +# Here you can overwrite main key you could find in mkdocs.yaml + +# The name of your site, if not specified, will be the entry `name` of the repo in +# `_data/repo_name.yaml` +#site_name: "Your Site Name" + +# The site description of your site, if not specified will be the description +# of the repo in `_data/repo_name.yaml` +#site_desc: "A short description" + +# The url of your site, if not specified, then the site_url will be build from +# the key `site_base_url` below and the `url_slug_with_namespace` in +# `_data/repo_name.yaml`. If `site_base_url` is not specified, then value of +# `site_url` will not be overwritten. +#site_url: "https://my_site.tld" + +# The name or company which old the copyright. No need to specify any date +# as it will be built based on the first commit of your repo. If not specify, +# then no copyright will be shown on the footer of the documentation. +#copyright: "Firstname Lastname" + +# Name of your repo, if not specified, will be the key `mkdocs_repo_name` in +# `_data/repo_name.yaml` If value is EXACTLY "!!git_platform", then the value +# will be `git_platform["name"]` (see below). +#repo_name: "My Repo Name" + +# URL to the source code of your repo. If not specified, will be build from +# `git_platform["url"]` (see below) and `repo_name["git_slug_with_namespace"]` +# in `_data/repo_name.yaml`. +#repo_url: "https://mygit.tld/namespace/repo_name + +# You can override every entry of the `theme` key in `mkdocs.yaml`, here. +# Usefull to override templated mkdocs. +# +# REMARK, ONLY FOR MATERIAL-MKDOCS THEME +# If `theme["logo"]` is not specified, i.e. path to the logo image, then it +# will be set to the value of the key `repo_name["logo"]` in +# `_data/repo_name.yaml` if specified. +# +# If `theme["favicon"]` is not specified, i.e. path to the favicon image, +# then it will be set to the value of the key `repo_name["logo"]` in +# `_data/repo_name.yaml` if specified. +# +# If `theme["icon"]["repo"]` is not specified, i.e. icon "path" (see +# https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/) that +# will be shown on the top rigt corner in front off the repo name, then it +# will be set to the value of the key `git_platform["icon"]` (see below). +#theme: +# logo: "path/to/logo.svg" +# icon: +# repo: fontawesome/brands/gitlab +# favicon: "path/to/favicon.svg" + +# Main repo configuration +# --------------------------------------------------------------------------- +# Here you can specify variable about your main repo documentation + +# The base url of your site, e.g. if you are using multiple nested +# documentation build with monorepo, you might want to share the same base URL +# for all your repo, then build link from the repo["url_slug_with_namespace"]. +#site_url: "https://my_site.tld" + + +# Git platform +# --------------------------------------------------------------------------- +# In this REQUIRED section you will be able to specify some information for you +# git platform hosting your repo. This section will be used to automatically +# setup configuration for mkdocs such as `repo_url`, theme["icon"]["repo"] etc. + +# Main dict entry +git_platform: + # The logo of the git platform you use. Not used in mkdocs configuration but + # can be used in markdown documentation file. + logo: " " + # Icon "path" (see + # https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/) that + # will be shown on the top rigt corner in front off the repo name if not + # specified in `theme["icon"]["repo"]`. + icon: "fontawesome/brands/gitlab" + # Name of the platform you use. + name: "Framagit" + # URL of the platform you use, to be able to set `repo_url` for mkdocs + # configuration. + url: "https://framagit.org/"