docs/_data/plugins.py

@@ -153,6 +153,10 @@ def add_external_to_nav(
                         repo_parent,
                         nav_parent[1:],
                     )
+    elif repo_dict["online_url"].startswith('/'):
+        nav.append({
+            repo_dict["nav_entry"]: repo_dict["online_url"].replace('/','../',1)
+        })
     else:
         nav.append({repo_dict["nav_entry"]: repo_dict["online_url"]})
 
@@ -822,21 +826,26 @@ def update_version(env: dict) -> None:
     mike_version = list()
     last_major = -1
     last_minor = -1
-    last_patch = -1
+    last_patch = str(-1)
     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])
+        patch = str()
+        for i_remain_tag in i_tag[2:]:
+            if i_remain_tag and i_remain_tag not in ("","\n"):
+                i_remain_tag = i_remain_tag.replace("\n","")
+                if not patch:
+                    patch = f"{i_remain_tag}"
+                else:
+                    patch = f"{patch}.{i_remain_tag}"
         if major > last_major:
             if last_major >= 0:
                 mike_version.append(
                     {
-                        "version": "{}.{}".format(last_major, last_minor),
-                        "title": "{}.{}.{}".format(
-                            last_major, last_minor, last_patch
-                        ),
+                        "version": f"{last_major}.{last_minor}",
+                        "title": f"{last_major}.{last_minor}.{last_patch}",
                         "aliases": [],
                     }
                 )
@@ -846,21 +855,20 @@ def update_version(env: dict) -> None:
             if last_minor >= 0:
                 mike_version.append(
                     {
-                        "version": "{}.{}".format(last_major, last_minor),
-                        "title": "{}.{}.{}".format(
-                            last_major, last_minor, last_patch
-                        ),
+                        "version": f"{last_major}.{last_minor}",
+                        "title": f"{last_major}.{last_minor}.{last_patch}",
                         "aliases": [],
                     }
                 )
             last_minor = minor
-            last_patch = -1
+            last_patch = str(-1)
         if patch > last_patch:
-            last_patch = patch
+            last_patch = str(patch)
+
     mike_version.append(
         {
-            "version": "{}.{}".format(last_major, last_minor),
-            "title": "{}.{}.{}".format(last_major, last_minor, last_patch),
+            "version": f"{last_major}.{last_minor}",
+            "title": f"{last_major}.{last_minor}.{last_patch}",
             "aliases": ["latest"],
         }
     )
@@ -914,9 +922,11 @@ def define_env(env: dict) -> None:
             var: Key in env.variables to return.
 
         Returns:
-            The value of `env.variables[var]`.
+            The value of `env.variables[var]` if it exists, else return None.
         """
-        return env.variables[var]
+        if var in env.variables:
+            return env.variables[var]
+        return None
 
     @env.macro
     # pylint: disable=W0612

docs/_data/template/repo.tpl.yaml

+
 ### BEGIN MKDOCS TEMPLATE ###
 ### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###
 ### Modified content will be overwritten when updating.###
@@ -29,11 +30,13 @@ repo_name:
 
   # (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"
+  # `assets/img/meta/repo_name_logo.png`
+  #logo: "assets/img/meta/repo_name_logo.png"
   # Description of the repo, will be used to setup the mkdocs description.
   desc: >-
-    Repo description with markdown support
+    An explicit description to explain what my repo do. Can be a multiline
+    description with **markdown** support such as
+    [link](https://url.domain.tld) and more.
 
   # (OPTIONAL) If you plan to use `mkdocstring` plugins to render python
   # source code, you will need to provide the path where your source files
@@ -47,3 +50,4 @@ repo_name:
     - name: "Firstname Lastname"
       mail: "mail@domain.tld"
 ### END MKDOCS TEMPLATE ###
+

docs/_data/template/subrepo.tpl.yaml

+
 ### BEGIN MKDOCS TEMPLATE ###
 ### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###
 ### Modified content will be overwritten when updating.###
@@ -25,6 +26,10 @@ subrepo:
   #     - name: subrepo_1
   #       # SSH or HTTP link to the online subrepo_1
   #       git_url: git@domain.tld:namesapce/subrepo_1
+  #       # Key `subpath` is a str pointing to the path in the subrepo where
+  #       # there is a file `mkdocs.yaml` and folder `docs` if not the root
+  #       # of the subrepo
+  #       subpath: sub/dir/
   #   # List of subdirectory from `dir_name` which are repos with
   #   # mkdocs documentation which will be included in the documentation.
   #   external:
@@ -34,6 +39,10 @@ subrepo:
   #     - name: subrepo_2
   #       # SSH or HTTP link to the online subrepo_2
   #       git_url: git@domain.tld:namesapce/subrepo_2
+  #       # Key `subpath` is a str pointing to the path in the subrepo where
+  #       # there is a file `mkdocs.yaml` and folder `docs` if not the root
+  #       # of the subrepo
+  #       subpath: sub/dir/
   #   # Another sub dir_name which also old subrepos
   #   subdir_name:
   #     nav_entry: "Sub Nav Entry"
@@ -75,3 +84,4 @@ subrepo:
   #     - Mkdocs Template: /my_program/mkdocs_template/
   # ```
 ### END MKDOCS TEMPLATE ###
+

docs/about/contributing.md

 {% set curr_repo=subs("mkdocs_template") %}
 
+
 <!-- BEGIN MKDOCS TEMPLATE -->
 <!--
 WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !
@@ -40,9 +41,9 @@ my projects. There you will find:
   * [Contributing workflow][contributing_workflow], which provide an example
    of the workflow I used for the development.
 
-[developers_guides]: {{ site_base_url }}/dev_guides/index.html
-[syntax_guide]: {{ site_base_url }}/dev_guides/style_guides/index.html
-[contributing_workflow]: {{ site_base_url }}/dev_guides/contributing_workflow.html
+[developers_guides]: {{ site_base_url }}/latest/dev_guides/index.html
+[syntax_guide]: {{ site_base_url }}/latest/dev_guides/style_guides/index.html
+[contributing_workflow]: {{ site_base_url }}/latest/dev_guides/developer_guidelines.html
 
 ## Community
 
@@ -52,3 +53,4 @@ conduct][code_of_conduct].
 [code_of_conduct]: code_of_conduct.md
 
 <!-- END MKDOCS TEMPLATE -->
+

docs/about/release_notes.md

@@ -10,6 +10,18 @@ Modified content will be overwritten when updating
 
 ## 🔖 v1.0
 
+### 🔖 v1.0.3 <small>(13/05/2021)</small>
+
+- 📝 Update documentation content.
+- 🔧 Update extra content through yaml `_data·` files
+    - Add new content
+    - Add documentation in template files
+- ✨ Improve `plugins.py` behaviour
+    - Convert `.format()` string into `f""` string
+    - Fix configuration management
+- ⬆📌 Upgrade pinned python dependencies
+
+
 ### 🔖 v1.0.2 <small>(29/04/2021)</small>
 
 - 📝📄 Update copyright in license content

docs/references/preview.md

@@ -10,36 +10,31 @@ Setup a temporary documentation folder to preview the rendering of the template
 
 This script will build the final list of folder that will be installed in
 the folder that will host the documenation and render a preview of such
-basic documenation based from template.
+basic documentation based from template.
 
 This will be done by creating symlinks from `templates` and `user_config`
 folders into `preview` folder.
 
 Available options are:
 
-  `-c,--clean`      : Remove every existing symlinks before rendering the
-                      preview.
+  * `-c,--clean`      : Remove every existing symlinks before rendering the
+                        preview.
 
-  `-r,--very-clean` : Remove every existing symlinks without rendering the
-                      preview.
+  * `-r,--very-clean` : Remove every existing symlinks without rendering the
+                        preview.
 
-  `-h,--help`       : Print this help.
+  * `-h,--help`       : Print this help.
 
 
 
 ## main()
 
- **Setup folder to be able to use directory environment mechanism**
- 
- Check if git is installed. Then check that folder is not already using
- mkdocs documentation.
- 
- If directory already set to use directory environment, then check if user
- explicitly tell to upgrade and upgrade, otherwise, print a warning and exit.
- 
- If directory not already set to use directory environment, clone
- user provided repo to a temporary folder, copy relevant scripts, files and
- folders to initiliaze a documentation rendered using mkdocs.
+ **Setup preview folder to be able to see the rendering of the documentation template.**
+
+ Build the list of the file that will be installed if using the mkdocs
+ documentation template, make a symlinks of all these files into `preview`
+ folder and, depending on the options provided, render the documentation
+ preview.
 
  **Globals**
 
@@ -54,9 +49,9 @@ Available options are:
 
  | Arguments | Description |
  | :-------- | :---------- |
- | `-u,--upgrade` | -u,--upgrade |
- | `-r,--repo-url REPO_URL` | -r,--repo-url REPO_URL |
- | `-s,--subrepo` | -s,--subrepo |
+ | `-c,--clean`      |  Remove every existing symlinks before rendering the preview. |
+ | `-r,--very-clean` |  Remove every existing symlinks without rendering the preview. |
+ | `-h,--help`       |  Print this help. |
 
  **Output**
 
@@ -64,13 +59,13 @@ Available options are:
 
  **Returns**
 
- - 0 if directory is correctly configure to start writing documentation
- - 1 if something when wrong during the setup of documentation
+ - 0, if rendering of the preview documentation went right.
+ - 1, if rendering of the preview documentation went wrong.
 
 ### manpage()
 
-> **Extract the script documentation from header and print it on stdout**
-> 
+> **Extract the script documentation from header and print it on stdout.**
+>
 > Simply extract the docstring from the header of the script, format it with
 > some output enhancement (such as bold) and print it to stdout.
 >
@@ -86,16 +81,16 @@ Available options are:
 
 ### mkdocs_log()
 
-> **Print debug message in colors depending on message severity on stderr**
-> 
+> **Print debug message in colors depending on message severity on stderr.**
+>
 > Echo colored log depending on user provided message severity. Message
 > severity are associated to following color output:
-> 
+>
 >   - `DEBUG` print in the fifth colors of the terminal (usually magenta)
 >   - `INFO` print in the second colors of the terminal (usually green)
 >   - `WARNING` print in the third colors of the terminal (usually yellow)
 >   - `ERROR` print in the third colors of the terminal (usually red)
-> 
+>
 > If no message severity is provided, severity will automatically be set to
 > INFO.
 >
@@ -119,7 +114,7 @@ Available options are:
 ### build_file_list()
 
 > **Recursively build a list of file from provided folder**
-> 
+>
 > Recursively build a list of file from provided folder and store such list
 > in a temporary bash array that must be set in parent method.
 >
@@ -128,18 +123,19 @@ Available options are:
 >
 > | Arguments | Description |
 > | :-------- | :---------- |
-> | `$1, string, absolute path to the folder which will be parsed` | $1, string, absolute path to the folder which will be parsed |
+> | `$1` |  string, absolute path to the folder which will be parsed |
 >
 >
 
 ### build_final_file_list()
 
-> **Replate templates file by user configured files**
-> 
+> **Build the merged list from `templates` and `user_config` folder.**
+>
 > If there is the same file in `user_config` and `templates` folder, then
 > replace the file to be installed from `templates` by the one in
 > `user_config`. Finally, add remaining `user_config` files not in
-> `templates` to the list of files to install or upgrade in a bash array.
+> `templates` to the list of files to install or upgrade in a bash array set
+> in parent method.
 >
 > **Globals**
 >
@@ -150,7 +146,8 @@ Available options are:
 ### clean_preview()
 
 > **Recursively clean the preview folder by removing all symlinks**
-> 
+>
+> Simply remove recursively all symlinks from folder `preview`.
 >
 > **Globals**
 >
@@ -165,11 +162,11 @@ Available options are:
 
 ### setup_mkdocs()
 
-> **Recursively install base folder and script to write mkdocs documentation.**
-> 
-> Build the list of files and folders, recursively copy all files to
-> their right location from the temporary clone repo to the folder which
-> will host the mkdocs documentation.
+> **Recursively install base folder and script to render a preview of the documentation template.**
+>
+> Build the list of files and folders, recursively create a symlink of all
+> files to their right location from the temporary clone repo to the folder
+> `preview`.
 >
 > **Globals**
 >

templates/docs/_data/plugins.py

@@ -100,6 +100,7 @@ def add_internal_to_nav(
     """
     if nav_parent:
         for i_nav in nav:
+            # "nav_entry" is a key of current parsed `nav`
             if nav_parent[0] in i_nav:
                 for i_key in i_nav:
                     add_internal_to_nav(
@@ -109,6 +110,16 @@ def add_internal_to_nav(
                         repo_parent,
                         nav_parent[1:],
                     )
+            # "nav_entry" is a subkey of current parsed `nav`
+            elif nav_parent[0] in yaml.dump(i_nav):
+                for i_key in i_nav:
+                    add_internal_to_nav(
+                        env,
+                        i_nav[i_key],
+                        repo_dict,
+                        repo_parent,
+                        nav_parent[0:],
+                    )
     else:
         mkdocs_path = env.project_dir
         for i_parent in repo_parent:
@@ -153,6 +164,14 @@ def add_external_to_nav(
                         repo_parent,
                         nav_parent[1:],
                     )
+    elif repo_dict["online_url"].startswith("/"):
+        nav.append(
+            {
+                repo_dict["nav_entry"]: repo_dict["online_url"].replace(
+                    "/", "../", 1
+                )
+            }
+        )
     else:
         nav.append({repo_dict["nav_entry"]: repo_dict["online_url"]})
 
@@ -225,13 +244,15 @@ def update_nav(
             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)
+                if nav_parent[0] not in yaml.dump(env.conf["nav"]):
+                    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)
+                if nav_parent[0] not in yaml.dump(env.conf["nav"]):
+                    add_nav_entry(env.conf["nav"], nav_parent)
                 add_external_to_nav(
                     env, env.conf["nav"], i_repo, repo_parent, nav_parent
                 )
@@ -402,9 +423,7 @@ def set_copyright(env: dict, git_repo: git.Repo) -> None:
         curr_year = time.strftime("%Y", time.localtime())
 
         if first_year == curr_year:
-            env.variables[
-                "date_copyright"
-            ] = f"Copyright © {curr_year}"
+            env.variables["date_copyright"] = f"Copyright © {curr_year}"
         else:
             env.variables[
                 "date_copyright"
@@ -415,7 +434,6 @@ def set_copyright(env: dict, git_repo: git.Repo) -> None:
         ] = f"{env.variables['date_copyright']} {env.variables['copyright']}"
 
 
-
 def set_repo_name(env: dict, repo_slug: str) -> None:
     """Update content of the `repo_name` key in `env.conf`.
 
@@ -557,7 +575,7 @@ def set_config(env: dict) -> None:
 
     if "subrepo" in env.variables:
         if (
-            env.variables["internal_subdoc"]
+            not env.variables["internal_subdoc"]
             and "monorepo" in env.conf["plugins"]
         ):
             env.conf["plugins"].pop("monorepo")
@@ -678,7 +696,7 @@ def update_subrepo_info(
                 f"{INFO_CLR}INFO [macros] - Pulling repo {i_repo['name']}{RESET_CLR}"
             )
             git_subrepo = git.Repo(subrepo_root)
-            git_subrepo.remotes.origin.pull()
+            git_subrepo.remotes.origin.pull('master')
         else:
             print(
                 f"{INFO_CLR}INFO [macros] - Cloning repo {i_repo['name']}{RESET_CLR}"
@@ -822,21 +840,26 @@ def update_version(env: dict) -> None:
     mike_version = list()
     last_major = -1
     last_minor = -1
-    last_patch = -1
+    last_patch = str(-1)
     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])
+        patch = str()
+        for i_remain_tag in i_tag[2:]:
+            if i_remain_tag and i_remain_tag not in ("", "\n"):
+                i_remain_tag = i_remain_tag.replace("\n", "")
+                if not patch:
+                    patch = f"{i_remain_tag}"
+                else:
+                    patch = f"{patch}.{i_remain_tag}"
         if major > last_major:
             if last_major >= 0:
                 mike_version.append(
                     {
-                        "version": "{}.{}".format(last_major, last_minor),
-                        "title": "{}.{}.{}".format(
-                            last_major, last_minor, last_patch
-                        ),
+                        "version": f"{last_major}.{last_minor}",
+                        "title": f"{last_major}.{last_minor}.{last_patch}",
                         "aliases": [],
                     }
                 )
@@ -846,21 +869,20 @@ def update_version(env: dict) -> None:
             if last_minor >= 0:
                 mike_version.append(
                     {
-                        "version": "{}.{}".format(last_major, last_minor),
-                        "title": "{}.{}.{}".format(
-                            last_major, last_minor, last_patch
-                        ),
+                        "version": f"{last_major}.{last_minor}",
+                        "title": f"{last_major}.{last_minor}.{last_patch}",
                         "aliases": [],
                     }
                 )
             last_minor = minor
-            last_patch = -1
+            last_patch = str(-1)
         if patch > last_patch:
-            last_patch = patch
+            last_patch = str(patch)
+
     mike_version.append(
         {
-            "version": "{}.{}".format(last_major, last_minor),
-            "title": "{}.{}.{}".format(last_major, last_minor, last_patch),
+            "version": f"{last_major}.{last_minor}",
+            "title": f"{last_major}.{last_minor}.{last_patch}",
             "aliases": ["latest"],
         }
     )
@@ -914,9 +936,11 @@ def define_env(env: dict) -> None:
             var: Key in env.variables to return.
 
         Returns:
-            The value of `env.variables[var]`.
+            The value of `env.variables[var]` if it exists, else return None.
         """
-        return env.variables[var]
+        if var in env.variables:
+            return env.variables[var]
+        return None
 
     @env.macro
     # pylint: disable=W0612