From db1dfc08a088d325dd4138bf72a0f84db19ef58e Mon Sep 17 00:00:00 2001 From: Romain Deville <code@romaindeville.fr> Date: Fri, 16 Apr 2021 18:01:28 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=9A=A8=20Fix=20tox=20warning=20&=20?= =?UTF-8?q?=F0=9F=92=A1=20Add=20source=20code=20doc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Due to error when running tox, adding better docstring in `plugin.py` and update content of `plugin.py` to fix pylint error. Update and --- docs/_data/plugins.py | 447 ++++++++++++++++++++++++-------- templates/docs/_data/plugins.py | 434 +++++++++++++++++++++++-------- 2 files changed, 669 insertions(+), 212 deletions(-) diff --git a/docs/_data/plugins.py b/docs/_data/plugins.py index 37f3ebd..ece11ce 100644 --- a/docs/_data/plugins.py +++ b/docs/_data/plugins.py @@ -1,7 +1,19 @@ #!/usr/bin/env python3 """ -Set of method for mkdocs-macros which also update nav entry to dynamically -support subrepo with mkdocs monorepo plugin. +Set of methods for +[mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) Set of +which : + +- Define macros usable in jinja template +- Update `env.conf`, i.e. mkdocs configuration based on variables files +- Dynamically update `env` dictionary and `nav` entries to support subrepo + either internal subrepo, using + [mkdocs-monorepo-plugin](https://github.com/backstage/mkdocs-monorepo-plugin), + or external subrepo by using `online_url` of such subrepo. + +This script allow to make content of `mkdocs.yml` to be templated, i.e. using +the same `mkdocs.yml` file for multiple repos and use variables files in +`docs/_data/` """ # pylint: disable=R0801 @@ -22,10 +34,6 @@ import os # 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 @@ -38,6 +46,10 @@ import time # https://pypi.org/project/GitPython/ import git +# Python implementation of Markdown +# https://pypi.org/project/markdown/ +import markdown + # YAML parser and emitter for Python # https://pypi.org/project/PyYAML/ import yaml @@ -49,13 +61,13 @@ from pykwalify.core import Core as yamlschema # pylint: disable=W0105 # - W0105: String statement has no effect LOG = logging.getLogger(__name__) -"""The logger facilty""" +"""The logger facilty.""" ERR_CLR = "\033[31m" -"""String coloring error output in red""" +"""String coloring error output in red.""" INFO_CLR = "\033[32m" -"""String coloring error output in green""" +"""String coloring error output in green.""" RESET_CLR = "\033[0m" -"""String reseting coloring output""" +"""String reseting coloring output.""" def add_internal_to_nav( @@ -65,8 +77,25 @@ def add_internal_to_nav( repo_parent: list, nav_parent: list = None, ) -> None: - """ - @rdeville TODO + """Add internal subrepo to `nav` key of mkdocs.yml for monorepo. + + This method recursively parse `nav_parent` arguments to know where to + include the internal subrepo into `nav` key. + + Once determined, add the subrepo as a entry to the `nav` key, with the + format required by + [mkdocs-monorepo-plugin](https://github.com/backstage/mkdocs-monorepo-plugin). + + Args: + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) + nav : Navigation dictionary (subpart of it if called + recursively) + repo_dict : Repo dictionary from `subrepo.yml` file in `docs/_data/` + repo_parent : List of keys storing parent keys of the current + `repo_dict` from `subrepo.yml` file in `docs/_data` + nav_parent : List of keys storing parents `nav_entry` keys of the + current `repo_dict` from `subrepo.yml` file in `docs/_data` """ if nav_parent: for i_nav in nav: @@ -93,8 +122,24 @@ def add_internal_to_nav( def add_external_to_nav( env: dict, nav: dict, repo_dict: dict, repo_parent: list, nav_parent: list ) -> None: - """ - @rdeville TODO + """Add external subrepo to `nav` key of mkdocs.yml. + + This method recursively parse `nav_parent` arguments to know where to + include the external subrepo into `nav` key. + + Once determined, add the subrepo as a entry to the `nav` key, with the + `online_url` key of the current subrepo defined with `repo_dict` in file + `subrepo.yml` in `docs/_data`. + + Args: + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) + nav : Navigation dictionary (subpart of it if called recursively) + repo_dict : Repo dictionary from `subrepo.yml` file in `docs/_data/` + repo_parent : List of keys storing parent keys of the current + `repo_dict` from `subrepo.yml` file in `docs/_data` + nav_parent : List of keys storing parents `nav_entry` keys of the + current `repo_dict` from `subrepo.yml` file in `docs/_data` """ if nav_parent: for i_nav in nav: @@ -112,8 +157,14 @@ def add_external_to_nav( def add_nav_entry(nav: list, nav_parent: list = None) -> None: - """ - @rdeville TODO + """Create missing entry into `nav` key of `env.conf`. + + Recursively parse list `nav_parent` and create missing entry into key `nav` + of mkdocs.yml. + + Args: + nav : Navigation dictionary (subpart of it if called recursively) + nav_parent : List of keys storing parents `nav_entry` keys """ entry = dict() @@ -137,8 +188,30 @@ def update_nav( nav_parent: list = None, first_iteration=False, ) -> None: - """ - @rdeville TODO + """Meta method which dynamically update the `nav` key of `env.conf`. + + Recursively parse `repo_dict` (provided from `subrepo.yml` file in + `docs/_data`), depending on the content of the keys, method will: + + - Update the list of `nav_parent` and `repo_parent`, + - Call [add_nav_entry][plugins.add_nav_entry] to add missing entry to `nav` + key of `mkdocs.yml`, + - Call [add_external_to_nav][plugins.add_external_to_nav] to add external + subrepo to `nav` key of `mkdocs.yml`, + - Call [add_internal_to_nav][plugins.add_internal_to_nav] to add internal + subrepo to `nav` key of `mkdocs.yml`, + - Recursively call itself. + + Args: + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) + repo_dict : Repo dictionary from `subrepo.yml` file in `docs/_data/` + repo_parent : List of keys storing parent keys of the current + `repo_dict` from `subrepo.yml` file in `docs/_data` + nav_parent : List of keys storing parents `nav_entry` keys of the + current `repo_dict` from `subrepo.yml` file in `docs/_data` + first_iteration : Simple boolean to know if it is the first recursive + call of the method. """ for i_key in repo_dict: if not nav_parent or first_iteration: @@ -166,17 +239,24 @@ def update_nav( 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 +def get_repo_slug(env: dict, git_repo: git.Repo) -> str: + """Compute the slug of the `git_repo` and ensure repo dictionary is defined. + + Compute the slug of the repo provided as `git_repo` based on the origin + remote. If no remo, then will use the folder name. - 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. + Else, update value of `env.variables["git"]` and return the `repo_slug`. + Arguments: - env: Mkdocs macro plugin environment dictionary. + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) git_repo: Git python object of the current repo. + + Returns: + Posix path from `os.path` python library. """ if git_repo.remotes: repo_slug = ( @@ -189,7 +269,7 @@ def get_repo_slug(env, git_repo): if repo_slug not in env.variables: LOG.error( - "%s[macros] - Dictionnary %s is not defined.%s", + "%s[macros] - Dictionary %s is not defined.%s", ERR_CLR, repo_slug, RESET_CLR, @@ -214,8 +294,16 @@ def get_repo_slug(env, git_repo): return repo_slug -def set_site_name(env, repo_slug): - """Update content of the `site_name` key in mkdocs.yml +def set_site_name(env: dict, repo_slug: str) -> None: + """Update content of the `site_name` key in `env.conf`. + + Update the value of `site_name` keys for mkdocs documentation based on (in + precedence order): + + - Value of `site_name` in `mkdocs.yml`, + - Value of `site_name` in `env.variables`, from `docs/_data/vars.yml`, + - Value of `name` in `env.variables[repo_slug]` from `docs/_data/repo.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 @@ -232,12 +320,15 @@ def set_site_name(env, repo_slug): 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 +def set_site_desc(env: dict, repo_slug: str) -> None: + """Update content of the `site_desc` key in `env.conf`. - 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`. + Update the value of `site_desc` keys for mkdocs configuration based on (in + precedence order): + + - Value of `site_desc` in `mkdocs.yml`, + - Value of `site_desc` in `env.variables`, from `docs/_data/vars.yml`, + - Value of `desc` in `env.variables[repo_slug]` from `docs/_data/repo.yml`. Arguments: env: Mkdocs macro plugin environment dictionary. @@ -250,12 +341,17 @@ def set_site_desc(env, repo_slug): 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 +def set_site_url(env: dict, repo_slug: str) -> None: + """Update content of the `site_url` key in `env.conf`. + + Update the value of `site_url` key for mkdocs documentation based on (in + precedence order): - 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. + - Value of `site_url` in `mkdocs.yml`, + - Value of `site_url` in `env.variables`, from `docs/_data/vars.yml`, + - Value of `site_base_url` in `env.variables`, from `docs/_data/vars.yml`, + concatenate with `env.variables[repo_slug]["url_slug_with_namespace"]` + from `docs/_data/repo.yml`. Arguments: env: Mkdocs macro plugin environment dictionary. @@ -272,12 +368,21 @@ def set_site_url(env, repo_slug): env.conf["site_url"] = site_url -def set_copyright(env, git_repo): - """Update content of the `copyright` key in mkdocs.yml +def set_copyright(env: dict, git_repo: git.Repo) -> None: + """Update content of the `copyright` key in `env.conf`. + + Update the value of `copyright` key for mkdocs documentation based on (in + precedence order): - 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. + - Value of `copyright` in `mkdocs.yml`, + - Value of `copyright` in `env.variables`, from `docs/_data/vars.yml`, then, + using this value: + - Value of the year of the first commit of the repo holding the + documentation and current year, + - Value of the current year only, + + If no `copyright` key defined, neither in `mkdocs.yml`, nor in + `docs/_data/vars.yml`, then not copyright will be set. Arguments: env: Mkdocs macro plugin environment dictionary. @@ -295,16 +400,25 @@ def set_copyright(env, git_repo): first_year = time.strftime("%Y", time.localtime()) curr_year = time.strftime("%Y", time.localtime()) - env.conf["copyright"] = f"Copyright © {first_year} - {curr_year} {env.variables['copyright']}" + env.conf[ + "copyright" + ] = f"Copyright © {first_year} - {curr_year} {env.variables['copyright']}" + +def set_repo_name(env: dict, repo_slug: str) -> None: + """Update content of the `repo_name` key in `env.conf`. -def set_repo_name(env, repo_slug): - """Update content of the `repo_url` key in mkdocs.yml + Update the value of `repo_name` key for mkdocs documentation based on (in + precedence order): - 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. + - Value of `repo_name` in `mkdocs.yml`, + - Value of `repo_name` in `env.variables`, from `docs/_data/vars.yml`, + - Value of `name` in `env.variables[repo_slug]`, from `docs/_data/repo.yml`, + then, depending on its value: + - If value is `!!git_platform`, then value of `repo_name` will be set to + the value of `env.variables['git_platform']['name']`, from + `docs/_data/vars.yml` + - Else, value is key `name` of `env.variables[repo_slug] Arguments: env: Mkdocs macro plugin environment dictionary. @@ -312,20 +426,26 @@ def set_repo_name(env, repo_slug): """ if "repo_name" not in env.conf or not env.conf["repo_name"]: - if "name" in env.variables[repo_slug]: + if "repo_name" in env.variables: + env.conf["repo_name"] = env.variables["repo_name"] + elif "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 +def set_repo_url(env: dict, repo_slug: str) -> None: + """Update content of the `repo_url` key in `env.conf`. + + Update the value of `repo_url` key for mkdocs documentation based on (in + precedence order): - 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. + - Value of `repo_url` in `mkdocs.yml`, + - Value of `repo_url` in `env.variables`, from `docs/_data/vars.yml`, + - Concatenation of the `url` of `env.variables['git_platform']`, from + `docs/_data/vars.yml` and value `git_slug_with_namespace` in + `env.variables[repo_slug]`, from `docs/_data/repo.yml`. Arguments: env: Mkdocs macro plugin environment dictionary. @@ -335,14 +455,17 @@ def set_repo_url(env, repo_slug): if "repo_url" in env.variables: env.conf["repo_url"] = env.variables["repo_url"] elif "repo_url" in env.conf: - env.conf["repo_url"] = f"{env.variables['git_platform']['url']}{env.variables[repo_slug]['git_slug_with_namespace']}" + env.conf["repo_url"] = ( + f"{env.variables['git_platform']['url']}" + + f"{env.variables[repo_slug]['git_slug_with_namespace']}" + ) -def update_theme(env, repo_slug): - """Update content of the `theme` key in mkdocs.yml +def update_theme(env: dict, repo_slug: str) -> None: + """Update content of the `theme` key in `env.conf`. If `theme` key is defined in `docs/_data/vars.yml`, this override the - content of the default `theme` key in `mkdocs.yml`. + content of the default `theme` key in mkdocs documentation. Arguments: env: Mkdocs macro plugin environment dictionary. @@ -380,13 +503,14 @@ def update_theme(env, repo_slug): def set_config(env: dict) -> None: - """Dynamically update mkdocs configuration + """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. + Based on the `repo_slug` (or folder name) load variables in + `docs/_data/vars.yml`, in `docs/_data/repo.yml` and update content of mkdocs + documentation accordingly. - Especially, if `docs/_data/subrepo.yaml` exists and define valid subrepod, - dynamically add these subrepo to the `nav` key of the mkdocs.yml + Especially, if `docs/_data/subrepo.yaml` exists and define valid subrepos, + clone these subrepo and dynamically add them to the `nav` key of the mkdocs configuration. Arguments: @@ -421,6 +545,9 @@ def load_yaml_file(path: str, filename: str) -> None: validate its content. If content is not valid, an error will be raised. Otherwise, its content will be returned. + If filename is `extra.yml` or `extra.yaml`, load content of the file + unconditionnally. + Arguments: path: Base path where YAML files are. filename: Name of the YAML file to load. @@ -429,29 +556,64 @@ def load_yaml_file(path: str, filename: str) -> None: 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") + if filename not in ("extra.yaml", "extra.yml"): + 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") + elif filename not in ("extra.yaml", "extra.yml"): + 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) + data_content = schema.source else: - schema_file = os.path.join(schema_file, "repo.schema.yaml") - data_type = "repo" + with open(filename) as file: + data_content = yaml.safe_load(file) - schema = yamlschema(source_file=source_file, schema_files=[schema_file]) - schema.validate(raise_exception=True) - return schema.source, data_type + return data_content, data_type -def update_subrepo_logo_src(env:dict,curr_repo:dict,repo_name:str,subrepo_dict:dict, path:str,external:bool) -> None: +# pylint: disable=R0913 +# - R0913: Too many arguments +def update_subrepo_logo_src( + env: dict, + curr_repo: dict, + repo_name: str, + subrepo_dict: dict, + path: str, + external: bool, +) -> None: + """Update the content of the key `logo` and `src_path` of subrepo + + Update value of keys `logo` and `src_path` of cloned subrepo, i.e. value + from file `docs/_data/repo.yaml` in the cloned subrepo, relative to the main + repo holding the documentation. + + Args: + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) + curr_repo : Repo dictionary from `repo.yml` file in `docs/_data/` in the + cloned subrepo, + repo_name: Name of the repo, + subrepo_dict: Dictionary of the repo as defined in file `subrepo.yaml` + in `docs/_data`, + path: Absolute path of the location of the cloned subrepo, + external: Boolean to know if current repo is an external subrepo. + """ 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) + 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") + 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) @@ -460,9 +622,25 @@ def update_subrepo_logo_src(env:dict,curr_repo:dict,repo_name:str,subrepo_dict:d ]["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 +def update_subrepo_info( + env: dict, subrepo_list: dict, path: str, external: bool = False +) -> dict: + """Clone subrepo, load repo information and update values if needed. + + Recursively clone or pull repo defined from subpart of + `env.variables['subrepo'], load repo information from this cloned or pulled + repo, i.e. load file `docs/_data/repo.yaml` in the subrepo, and update + needed keys. + + Args: + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) + subrepo_list: List of dictionary storing subrepo dict, + path: Absolute path of the location of the cloned subrepo, + external: Boolean to know if current repo is an external subrepo. + + Return: + A updating dictionary storing subrepo information """ return_dict = dict() for i_repo in subrepo_list: @@ -491,14 +669,33 @@ def update_subrepo_info(env: dict, subrepo_list: dict, path: str, external:bool 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) + 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 +def update_subrepo( + env: dict, subrepo_dict: dict, path: str, external: bool +) -> dict: + """Recursively parse `env.variables['subrepo']`. + + Recursively parse dictionary `env.variables['subrepo']`, from file + `docs/_data/subrepo.yaml`. Depending on the key: + + - `nav_entry`: Do a recursion of this method, + - `external` or `internal`: Parse the list to update subrepo information + + Args: + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) + subrepo_dict: Dictionary storing subrepo, + path: Absolute path of the location of the cloned subrepo, + external: Boolean to know if current repo is an external subrepo. + + Returns: + An updated dictionary of repo informations. """ return_dict = dict() for i_key in subrepo_dict: @@ -508,24 +705,45 @@ def update_subrepo(env: dict, subrepo_dict: dict, path: str, external:bool) -> d elif i_key == "internal": env.variables["internal_subdoc"] = True return_dict.update( - update_subrepo_info(env, subrepo_dict[i_key], path,external) + 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 + 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: +def update_logo_src_repo( + env: dict, curr_repo: dict, repo_name: str, path: str = None +) -> None: + """Update the content of the key `logo` and `src_path` of current repo + + Update value of keys `logo` and `src_path` of current repo holding the + documentation. + + Args: + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) + curr_repo : Repo dictionary from `repo.yml` file in `docs/_data/` in the + cloned subrepo, + repo_name: Name of the repo, + path: Absolute path of the location of the current repo. + """ + subpath = "" if path: - subpath = os.path.join(path.replace(env.project_dir,""),repo_name) + 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") + 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) @@ -534,15 +752,15 @@ def update_logo_src_repo(env:dict,curr_repo:dict,repo_name:str,path:str=None) -> ]["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 variables files in `docs/_data/` - Load every yaml files in docs/_data/, if one of the file define a `subrepo` - key, load every variables associated to subrepo. + Load every yaml files in `docs/_data/`, if one of the file define the + current repo, then update keys `logo` and `src_path` for the current repo. Arguments: - env: Mkdocs macro plugin environment dictionary. + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) """ var_dir = os.path.join(env.project_dir, "docs", "_data") @@ -551,15 +769,22 @@ def load_var_file(env: dict) -> None: 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) + 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 + """Parse every tags of the repo to build a `docs/versions.json` + + To emulate mike version support for gitlab, this method will parse every + tags of the current repo holding the current documentation to create a file + `versions.json` which will be put in folder `docs`. + + This is mainly used for the CI to build a documentation per repo tags. Arguments: - env: Mkdocs macro plugin environment dictionary. + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) """ if ( "version" not in env.variables @@ -581,8 +806,10 @@ def update_version(env: dict) -> None: if major > last_major: mike_version.append( { - "version": f"{last_major}.{last_minor}", - "title": f"{last_major}.{last_minro}.{last_patch}", + "version": "{}.{}".format(last_major, last_minor), + "title": "{}.{}.{}".format( + last_major, last_minor, last_patch + ), "aliases": [], } ) @@ -591,8 +818,10 @@ def update_version(env: dict) -> None: if minor > last_minor: mike_version.append( { - "version": f"{last_major}.{last_minor}", - "title": f"{last_major}.{last_minor}.{last_patch}", + "version": "{}.{}".format(last_major, last_minor), + "title": "{}.{}.{}".format( + last_major, last_minor, last_patch + ), "aliases": [], } ) @@ -602,8 +831,8 @@ def update_version(env: dict) -> None: last_patch = patch mike_version.append( { - "version": f"{last_major}.{last_minor}", - "title": f"{last_major}.{last_minor}.{last_patch}", + "version": "{}.{}".format(last_major, last_minor), + "title": "{}.{}.{}".format(last_major, last_minor, last_patch), "aliases": ["latest"], } ) @@ -626,6 +855,9 @@ def define_env(env: dict) -> None: See [https://mkdocs-macros-plugin.readthedocs.io/en/latest/](https://mkdocs-macros-plugin.readthedocs.io/en/latest/) + This hooks also start the initialization of the dynamic configuration of + mkdocs. + Arguments: env: Mkdocs macro plugin environment dictionary. """ @@ -635,7 +867,9 @@ def define_env(env: dict) -> None: if "subrepo" in env.variables: env.variables["internal_subdoc"] = False env.variables.update( - update_subrepo(env, env.variables["subrepo"], env.project_dir, False) + update_subrepo( + env, env.variables["subrepo"], env.project_dir, False + ) ) set_config(env) @@ -652,10 +886,9 @@ def define_env(env: dict) -> None: @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)] + def to_html(var: str) -> dict: + """Convert the content of the markdown string into HTML""" + return markdown.markdown(var) # ----------------------------------------------------------------------------- diff --git a/templates/docs/_data/plugins.py b/templates/docs/_data/plugins.py index f2a9800..ece11ce 100644 --- a/templates/docs/_data/plugins.py +++ b/templates/docs/_data/plugins.py @@ -1,7 +1,19 @@ #!/usr/bin/env python3 """ -Set of method for mkdocs-macros which also update nav entry to dynamically -support subrepo with mkdocs monorepo plugin. +Set of methods for +[mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) Set of +which : + +- Define macros usable in jinja template +- Update `env.conf`, i.e. mkdocs configuration based on variables files +- Dynamically update `env` dictionary and `nav` entries to support subrepo + either internal subrepo, using + [mkdocs-monorepo-plugin](https://github.com/backstage/mkdocs-monorepo-plugin), + or external subrepo by using `online_url` of such subrepo. + +This script allow to make content of `mkdocs.yml` to be templated, i.e. using +the same `mkdocs.yml` file for multiple repos and use variables files in +`docs/_data/` """ # pylint: disable=R0801 @@ -22,10 +34,6 @@ import os # 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 @@ -38,6 +46,10 @@ import time # https://pypi.org/project/GitPython/ import git +# Python implementation of Markdown +# https://pypi.org/project/markdown/ +import markdown + # YAML parser and emitter for Python # https://pypi.org/project/PyYAML/ import yaml @@ -49,13 +61,13 @@ from pykwalify.core import Core as yamlschema # pylint: disable=W0105 # - W0105: String statement has no effect LOG = logging.getLogger(__name__) -"""The logger facilty""" +"""The logger facilty.""" ERR_CLR = "\033[31m" -"""String coloring error output in red""" +"""String coloring error output in red.""" INFO_CLR = "\033[32m" -"""String coloring error output in green""" +"""String coloring error output in green.""" RESET_CLR = "\033[0m" -"""String reseting coloring output""" +"""String reseting coloring output.""" def add_internal_to_nav( @@ -65,8 +77,25 @@ def add_internal_to_nav( repo_parent: list, nav_parent: list = None, ) -> None: - """ - @rdeville TODO + """Add internal subrepo to `nav` key of mkdocs.yml for monorepo. + + This method recursively parse `nav_parent` arguments to know where to + include the internal subrepo into `nav` key. + + Once determined, add the subrepo as a entry to the `nav` key, with the + format required by + [mkdocs-monorepo-plugin](https://github.com/backstage/mkdocs-monorepo-plugin). + + Args: + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) + nav : Navigation dictionary (subpart of it if called + recursively) + repo_dict : Repo dictionary from `subrepo.yml` file in `docs/_data/` + repo_parent : List of keys storing parent keys of the current + `repo_dict` from `subrepo.yml` file in `docs/_data` + nav_parent : List of keys storing parents `nav_entry` keys of the + current `repo_dict` from `subrepo.yml` file in `docs/_data` """ if nav_parent: for i_nav in nav: @@ -93,8 +122,24 @@ def add_internal_to_nav( def add_external_to_nav( env: dict, nav: dict, repo_dict: dict, repo_parent: list, nav_parent: list ) -> None: - """ - @rdeville TODO + """Add external subrepo to `nav` key of mkdocs.yml. + + This method recursively parse `nav_parent` arguments to know where to + include the external subrepo into `nav` key. + + Once determined, add the subrepo as a entry to the `nav` key, with the + `online_url` key of the current subrepo defined with `repo_dict` in file + `subrepo.yml` in `docs/_data`. + + Args: + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) + nav : Navigation dictionary (subpart of it if called recursively) + repo_dict : Repo dictionary from `subrepo.yml` file in `docs/_data/` + repo_parent : List of keys storing parent keys of the current + `repo_dict` from `subrepo.yml` file in `docs/_data` + nav_parent : List of keys storing parents `nav_entry` keys of the + current `repo_dict` from `subrepo.yml` file in `docs/_data` """ if nav_parent: for i_nav in nav: @@ -112,8 +157,14 @@ def add_external_to_nav( def add_nav_entry(nav: list, nav_parent: list = None) -> None: - """ - @rdeville TODO + """Create missing entry into `nav` key of `env.conf`. + + Recursively parse list `nav_parent` and create missing entry into key `nav` + of mkdocs.yml. + + Args: + nav : Navigation dictionary (subpart of it if called recursively) + nav_parent : List of keys storing parents `nav_entry` keys """ entry = dict() @@ -137,8 +188,30 @@ def update_nav( nav_parent: list = None, first_iteration=False, ) -> None: - """ - @rdeville TODO + """Meta method which dynamically update the `nav` key of `env.conf`. + + Recursively parse `repo_dict` (provided from `subrepo.yml` file in + `docs/_data`), depending on the content of the keys, method will: + + - Update the list of `nav_parent` and `repo_parent`, + - Call [add_nav_entry][plugins.add_nav_entry] to add missing entry to `nav` + key of `mkdocs.yml`, + - Call [add_external_to_nav][plugins.add_external_to_nav] to add external + subrepo to `nav` key of `mkdocs.yml`, + - Call [add_internal_to_nav][plugins.add_internal_to_nav] to add internal + subrepo to `nav` key of `mkdocs.yml`, + - Recursively call itself. + + Args: + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) + repo_dict : Repo dictionary from `subrepo.yml` file in `docs/_data/` + repo_parent : List of keys storing parent keys of the current + `repo_dict` from `subrepo.yml` file in `docs/_data` + nav_parent : List of keys storing parents `nav_entry` keys of the + current `repo_dict` from `subrepo.yml` file in `docs/_data` + first_iteration : Simple boolean to know if it is the first recursive + call of the method. """ for i_key in repo_dict: if not nav_parent or first_iteration: @@ -166,17 +239,24 @@ def update_nav( 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 +def get_repo_slug(env: dict, git_repo: git.Repo) -> str: + """Compute the slug of the `git_repo` and ensure repo dictionary is defined. + + Compute the slug of the repo provided as `git_repo` based on the origin + remote. If no remo, then will use the folder name. - 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. + Else, update value of `env.variables["git"]` and return the `repo_slug`. + Arguments: - env: Mkdocs macro plugin environment dictionary. + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) git_repo: Git python object of the current repo. + + Returns: + Posix path from `os.path` python library. """ if git_repo.remotes: repo_slug = ( @@ -189,7 +269,7 @@ def get_repo_slug(env, git_repo): if repo_slug not in env.variables: LOG.error( - "%s[macros] - Dictionnary %s is not defined.%s", + "%s[macros] - Dictionary %s is not defined.%s", ERR_CLR, repo_slug, RESET_CLR, @@ -214,8 +294,16 @@ def get_repo_slug(env, git_repo): return repo_slug -def set_site_name(env, repo_slug): - """Update content of the `site_name` key in mkdocs.yml +def set_site_name(env: dict, repo_slug: str) -> None: + """Update content of the `site_name` key in `env.conf`. + + Update the value of `site_name` keys for mkdocs documentation based on (in + precedence order): + + - Value of `site_name` in `mkdocs.yml`, + - Value of `site_name` in `env.variables`, from `docs/_data/vars.yml`, + - Value of `name` in `env.variables[repo_slug]` from `docs/_data/repo.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 @@ -232,12 +320,15 @@ def set_site_name(env, repo_slug): 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 +def set_site_desc(env: dict, repo_slug: str) -> None: + """Update content of the `site_desc` key in `env.conf`. - 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`. + Update the value of `site_desc` keys for mkdocs configuration based on (in + precedence order): + + - Value of `site_desc` in `mkdocs.yml`, + - Value of `site_desc` in `env.variables`, from `docs/_data/vars.yml`, + - Value of `desc` in `env.variables[repo_slug]` from `docs/_data/repo.yml`. Arguments: env: Mkdocs macro plugin environment dictionary. @@ -250,12 +341,17 @@ def set_site_desc(env, repo_slug): 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 +def set_site_url(env: dict, repo_slug: str) -> None: + """Update content of the `site_url` key in `env.conf`. + + Update the value of `site_url` key for mkdocs documentation based on (in + precedence order): - 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. + - Value of `site_url` in `mkdocs.yml`, + - Value of `site_url` in `env.variables`, from `docs/_data/vars.yml`, + - Value of `site_base_url` in `env.variables`, from `docs/_data/vars.yml`, + concatenate with `env.variables[repo_slug]["url_slug_with_namespace"]` + from `docs/_data/repo.yml`. Arguments: env: Mkdocs macro plugin environment dictionary. @@ -272,12 +368,21 @@ def set_site_url(env, repo_slug): env.conf["site_url"] = site_url -def set_copyright(env, git_repo): - """Update content of the `copyright` key in mkdocs.yml +def set_copyright(env: dict, git_repo: git.Repo) -> None: + """Update content of the `copyright` key in `env.conf`. + + Update the value of `copyright` key for mkdocs documentation based on (in + precedence order): - 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. + - Value of `copyright` in `mkdocs.yml`, + - Value of `copyright` in `env.variables`, from `docs/_data/vars.yml`, then, + using this value: + - Value of the year of the first commit of the repo holding the + documentation and current year, + - Value of the current year only, + + If no `copyright` key defined, neither in `mkdocs.yml`, nor in + `docs/_data/vars.yml`, then not copyright will be set. Arguments: env: Mkdocs macro plugin environment dictionary. @@ -295,18 +400,25 @@ def set_copyright(env, git_repo): 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"] - ) + env.conf[ + "copyright" + ] = f"Copyright © {first_year} - {curr_year} {env.variables['copyright']}" + +def set_repo_name(env: dict, repo_slug: str) -> None: + """Update content of the `repo_name` key in `env.conf`. -def set_repo_name(env, repo_slug): - """Update content of the `repo_url` key in mkdocs.yml + Update the value of `repo_name` key for mkdocs documentation based on (in + precedence order): - 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. + - Value of `repo_name` in `mkdocs.yml`, + - Value of `repo_name` in `env.variables`, from `docs/_data/vars.yml`, + - Value of `name` in `env.variables[repo_slug]`, from `docs/_data/repo.yml`, + then, depending on its value: + - If value is `!!git_platform`, then value of `repo_name` will be set to + the value of `env.variables['git_platform']['name']`, from + `docs/_data/vars.yml` + - Else, value is key `name` of `env.variables[repo_slug] Arguments: env: Mkdocs macro plugin environment dictionary. @@ -314,20 +426,26 @@ def set_repo_name(env, repo_slug): """ if "repo_name" not in env.conf or not env.conf["repo_name"]: - if "name" in env.variables[repo_slug]: + if "repo_name" in env.variables: + env.conf["repo_name"] = env.variables["repo_name"] + elif "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 +def set_repo_url(env: dict, repo_slug: str) -> None: + """Update content of the `repo_url` key in `env.conf`. - 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. + Update the value of `repo_url` key for mkdocs documentation based on (in + precedence order): + + - Value of `repo_url` in `mkdocs.yml`, + - Value of `repo_url` in `env.variables`, from `docs/_data/vars.yml`, + - Concatenation of the `url` of `env.variables['git_platform']`, from + `docs/_data/vars.yml` and value `git_slug_with_namespace` in + `env.variables[repo_slug]`, from `docs/_data/repo.yml`. Arguments: env: Mkdocs macro plugin environment dictionary. @@ -337,17 +455,17 @@ def set_repo_url(env, repo_slug): 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"], + env.conf["repo_url"] = ( + f"{env.variables['git_platform']['url']}" + + f"{env.variables[repo_slug]['git_slug_with_namespace']}" ) -def update_theme(env, repo_slug): - """Update content of the `theme` key in mkdocs.yml +def update_theme(env: dict, repo_slug: str) -> None: + """Update content of the `theme` key in `env.conf`. If `theme` key is defined in `docs/_data/vars.yml`, this override the - content of the default `theme` key in `mkdocs.yml`. + content of the default `theme` key in mkdocs documentation. Arguments: env: Mkdocs macro plugin environment dictionary. @@ -385,13 +503,14 @@ def update_theme(env, repo_slug): def set_config(env: dict) -> None: - """Dynamically update mkdocs configuration + """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. + Based on the `repo_slug` (or folder name) load variables in + `docs/_data/vars.yml`, in `docs/_data/repo.yml` and update content of mkdocs + documentation accordingly. - Especially, if `docs/_data/subrepo.yaml` exists and define valid subrepod, - dynamically add these subrepo to the `nav` key of the mkdocs.yml + Especially, if `docs/_data/subrepo.yaml` exists and define valid subrepos, + clone these subrepo and dynamically add them to the `nav` key of the mkdocs configuration. Arguments: @@ -426,6 +545,9 @@ def load_yaml_file(path: str, filename: str) -> None: validate its content. If content is not valid, an error will be raised. Otherwise, its content will be returned. + If filename is `extra.yml` or `extra.yaml`, load content of the file + unconditionnally. + Arguments: path: Base path where YAML files are. filename: Name of the YAML file to load. @@ -434,29 +556,64 @@ def load_yaml_file(path: str, filename: str) -> None: 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") + if filename not in ("extra.yaml", "extra.yml"): + 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") + elif filename not in ("extra.yaml", "extra.yml"): + 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) + data_content = schema.source else: - schema_file = os.path.join(schema_file, "repo.schema.yaml") - data_type = "repo" + with open(filename) as file: + data_content = yaml.safe_load(file) - schema = yamlschema(source_file=source_file, schema_files=[schema_file]) - schema.validate(raise_exception=True) - return schema.source, data_type + return data_content, data_type -def update_subrepo_logo_src(env:dict,curr_repo:dict,repo_name:str,subrepo_dict:dict, path:str,external:bool) -> None: +# pylint: disable=R0913 +# - R0913: Too many arguments +def update_subrepo_logo_src( + env: dict, + curr_repo: dict, + repo_name: str, + subrepo_dict: dict, + path: str, + external: bool, +) -> None: + """Update the content of the key `logo` and `src_path` of subrepo + + Update value of keys `logo` and `src_path` of cloned subrepo, i.e. value + from file `docs/_data/repo.yaml` in the cloned subrepo, relative to the main + repo holding the documentation. + + Args: + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) + curr_repo : Repo dictionary from `repo.yml` file in `docs/_data/` in the + cloned subrepo, + repo_name: Name of the repo, + subrepo_dict: Dictionary of the repo as defined in file `subrepo.yaml` + in `docs/_data`, + path: Absolute path of the location of the cloned subrepo, + external: Boolean to know if current repo is an external subrepo. + """ 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) + 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") + 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) @@ -465,9 +622,25 @@ def update_subrepo_logo_src(env:dict,curr_repo:dict,repo_name:str,subrepo_dict:d ]["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 +def update_subrepo_info( + env: dict, subrepo_list: dict, path: str, external: bool = False +) -> dict: + """Clone subrepo, load repo information and update values if needed. + + Recursively clone or pull repo defined from subpart of + `env.variables['subrepo'], load repo information from this cloned or pulled + repo, i.e. load file `docs/_data/repo.yaml` in the subrepo, and update + needed keys. + + Args: + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) + subrepo_list: List of dictionary storing subrepo dict, + path: Absolute path of the location of the cloned subrepo, + external: Boolean to know if current repo is an external subrepo. + + Return: + A updating dictionary storing subrepo information """ return_dict = dict() for i_repo in subrepo_list: @@ -496,14 +669,33 @@ def update_subrepo_info(env: dict, subrepo_list: dict, path: str, external:bool 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) + 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 +def update_subrepo( + env: dict, subrepo_dict: dict, path: str, external: bool +) -> dict: + """Recursively parse `env.variables['subrepo']`. + + Recursively parse dictionary `env.variables['subrepo']`, from file + `docs/_data/subrepo.yaml`. Depending on the key: + + - `nav_entry`: Do a recursion of this method, + - `external` or `internal`: Parse the list to update subrepo information + + Args: + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) + subrepo_dict: Dictionary storing subrepo, + path: Absolute path of the location of the cloned subrepo, + external: Boolean to know if current repo is an external subrepo. + + Returns: + An updated dictionary of repo informations. """ return_dict = dict() for i_key in subrepo_dict: @@ -513,24 +705,45 @@ def update_subrepo(env: dict, subrepo_dict: dict, path: str, external:bool) -> d elif i_key == "internal": env.variables["internal_subdoc"] = True return_dict.update( - update_subrepo_info(env, subrepo_dict[i_key], path,external) + 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 + 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: +def update_logo_src_repo( + env: dict, curr_repo: dict, repo_name: str, path: str = None +) -> None: + """Update the content of the key `logo` and `src_path` of current repo + + Update value of keys `logo` and `src_path` of current repo holding the + documentation. + + Args: + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) + curr_repo : Repo dictionary from `repo.yml` file in `docs/_data/` in the + cloned subrepo, + repo_name: Name of the repo, + path: Absolute path of the location of the current repo. + """ + subpath = "" if path: - subpath = os.path.join(path.replace(env.project_dir,""),repo_name) + 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") + 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) @@ -539,15 +752,15 @@ def update_logo_src_repo(env:dict,curr_repo:dict,repo_name:str,path:str=None) -> ]["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 variables files in `docs/_data/` - Load every yaml files in docs/_data/, if one of the file define a `subrepo` - key, load every variables associated to subrepo. + Load every yaml files in `docs/_data/`, if one of the file define the + current repo, then update keys `logo` and `src_path` for the current repo. Arguments: - env: Mkdocs macro plugin environment dictionary. + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) """ var_dir = os.path.join(env.project_dir, "docs", "_data") @@ -556,15 +769,22 @@ def load_var_file(env: dict) -> None: 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) + 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 + """Parse every tags of the repo to build a `docs/versions.json` + + To emulate mike version support for gitlab, this method will parse every + tags of the current repo holding the current documentation to create a file + `versions.json` which will be put in folder `docs`. + + This is mainly used for the CI to build a documentation per repo tags. Arguments: - env: Mkdocs macro plugin environment dictionary. + env : Environment dictionary provided by + [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) """ if ( "version" not in env.variables @@ -635,6 +855,9 @@ def define_env(env: dict) -> None: See [https://mkdocs-macros-plugin.readthedocs.io/en/latest/](https://mkdocs-macros-plugin.readthedocs.io/en/latest/) + This hooks also start the initialization of the dynamic configuration of + mkdocs. + Arguments: env: Mkdocs macro plugin environment dictionary. """ @@ -644,7 +867,9 @@ def define_env(env: dict) -> None: if "subrepo" in env.variables: env.variables["internal_subdoc"] = False env.variables.update( - update_subrepo(env, env.variables["subrepo"], env.project_dir, False) + update_subrepo( + env, env.variables["subrepo"], env.project_dir, False + ) ) set_config(env) @@ -661,10 +886,9 @@ def define_env(env: dict) -> None: @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)] + def to_html(var: str) -> dict: + """Convert the content of the markdown string into HTML""" + return markdown.markdown(var) # ----------------------------------------------------------------------------- -- GitLab