Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found
Select Git revision
  • develop
  • master
  • v1.0.0
  • v1.0.1
  • v1.0.2
  • v1.0.3
6 results

Target

Select target project
No results found
Select Git revision
  • develop
  • master
  • v1.0.0
  • v1.0.1
  • v1.0.2
  • v1.0.3
  • v1.0.3-PAGoDA.1
  • v1.0.3-PAGoDA.2
8 results
Show changes

Commits on Source 51

41 files
+ 1975
− 504
Compare changes
  • Side-by-side
  • Inline

Files

.editorconfig

+4 −8
Original line number Original line Diff line number Diff line
@@ -14,21 +14,17 @@ insert_final_newline = false 
trim_trailing_whitespace = true

trim_trailing_whitespace = true

# Size of indentation (either tabs or space)

# Size of indentation (either tabs or space)

indent_size = 2

indent_size = 2

# Type of indentation (either tabs or space)

indent_style = space

# Maximum length (in number of chars) for a line

max_line_length = 80





# Python specific syntax

# Python specific syntax

[*.py]

[*.py]

# Type of indentation (either tabs or space)

indent_style = space

# Size of indentation (either tabs or space)

# Size of indentation (either tabs or space)

indent_size = 4

indent_size = 4

# Maximum length (in number of chars) for a line

max_line_length = 80





# Yaml specific syntax

# Yaml specific syntax

[*.{yaml,yml}]

[*.{yaml,yml}]

# Type of indentation (either tabs or space)

indent_style = space

# Size of indentation (either tabs or space)

indent_size = 2

# Maximum length (in number of chars) for a line

# Maximum length (in number of chars) for a line

max_line_length = 120
 
max_line_length = 120

.gitlab-ci.yml

+27 −58
Original line number Original line Diff line number Diff line
@@ -15,13 +15,10 @@ workflow: 
  rules:

  rules:

    # Do not run CI when commit title have

    # Do not run CI when commit title have

    # WIP, NO-CI or 🚧 (gitmoji for "work in progress", aka :construction:)

    # WIP, NO-CI or 🚧 (gitmoji for "work in progress", aka :construction:)

    - if: |

    - if: $CI_COMMIT_TITLE =~ /.*(WIP|NO-CI|🚧|:construction:).*/

        $CI_COMMIT_TITLE =~ /.*WIP.*/ ||

        $CI_COMMIT_TITLE =~ /.*NO-CI.*/ ||

        $CI_COMMIT_TITLE =~ /.*🚧.*/

      when: never

      when: never

    # Run the CI otherwise (depending on `only/except` key per jobs)

    # Do not run CI if repo is not on framagit

    - when: always

    - if: $CI_SERVER_HOST =~ /^framagit.org/





### BEGIN MKDOCS TEMPLATE ###

### BEGIN MKDOCS TEMPLATE ###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! ###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! ###
@@ -77,59 +74,31 @@ variables: 
    # Activate virtual environment

    # Activate virtual environment

    - source .venv/bin/activate

    - source .venv/bin/activate





# Only anchors

# Rules anchors

# -----------------------------------------------------------------------------

# -----------------------------------------------------------------------------

# https://docs.gitlab.com/ee/ci/yaml/README.html#only

# https://docs.gitlab.com/ee/ci/yaml/README.html#rules

# List all names of refs that can be used with key (only|except):refs using

# Defining bash regexp test

# anchors to avoid having to modify multiple times. Refs are:

.rules_regexp:

# - Branches names based on git flow: https://danielkummer.github.io/git-flow-cheatsheet/

  - &rules_regexp_dev $CI_COMMIT_BRANCH =~ /^((release|feature|hotfix|bugfix)-|merge_request_)*/

# - merge_requests (https://docs.gitlab.com/ee/ci/yaml/README.html#onlyexcept-basic)

  - &rules_regexp_pre_prod $CI_COMMIT_BRANCH =~ /(develop|master)/

# - tags (https://docs.gitlab.com/ee/ci/yaml/README.html#onlyexcept-basic)

  - &rules_regexp_prod $CI_COMMIT_TAG

.refs_names:



  - &ref_release /release-*/

# Defining rules that now replace only to run jobs under specific condition

  - &ref_feature /feature-*/

# and define variables

  - &ref_hotfix /hotfix-*/

.rules_dev: &rules_dev

  - &ref_bugfix /bugfix-*/

  if: *rules_regexp_dev

  - &ref_develop develop

  variables:

  - &ref_master master

    CI_DEPLOY_TYPE: "dev"

  - &ref_merge_requests merge_requests



  - &ref_tags tags

.rules_pre_prod: &rules_pre_prod



  if: *rules_regexp_pre_prod

# Specify on which branch, tags or on merge_requests CI should be done.

  variables:

# Jobs under only_dev anchor will be run if branch name are compliant with git

    CI_DEPLOY_TYPE: "pre_prod"

# flow branch which are not `develop` neither `master` and will be run on



# merge_request

.rules_prod: &rules_prod

.only_dev: &only_dev

  if: *rules_regexp_prod

  only:

  variables:

    refs:

    CI_DEPLOY_TYPE: "prod"

      - *ref_release

      - *ref_feature

      - *ref_hotfix

      - *ref_bugfix

      - *ref_merge_requests



# Jobs under only_pre_prod anchor will be run on `develop` (i.e. pre-release)

# and `master` (release) branch.

.only_pre_prod: &only_pre_prod

  only:

    refs:

      - *ref_develop

      - *ref_master



# Jobs under only_prod anchor will be run on tagged commit.

.only_prod: &only_prod

  only:

    refs:

      - *ref_tags



# Jobs under only_trigger anchor will be run on `develop` (i.e. pre-release)

# `master` (release) branch and tagged commit.

.only_trigger: &only_trigger

  only:

    refs:

      - *ref_develop

      - *ref_master

      - *ref_tags





# Tag anchors

# Tag anchors

# -----------------------------------------------------------------------------

# -----------------------------------------------------------------------------

.yamllint

+0 −5
Original line number Original line Diff line number Diff line
@@ -34,8 +34,3 @@ rules: 
    type: unix

    type: unix

  trailing-spaces: disable

  trailing-spaces: disable

  truthy: disable
 
  truthy: disable
 


# *****************************************************************************

# VIM MODELINE

# vim: ft=yaml: fdm=indent:

# *****************************************************************************

README.md

+7 −7
Original line number Original line Diff line number Diff line
@@ -12,8 +12,8 @@ 




--------------------------------------------------------------------------------

--------------------------------------------------------------------------------





Template to easily setup and managed [mkdocs][mkdocs] documentation in folder

Mkdocs Templates scaffolding project to host documentation configuration

to have homogenous documentation.

and themes to manage homogenous documentation accros multiple projects.





--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
@@ -49,13 +49,13 @@ projects. 
While [mkdocs][mkdocs] is a really usefull software allowing me to

While [mkdocs][mkdocs] is a really usefull software allowing me to

write clean and clear documentation in markdown and render it as static

write clean and clear documentation in markdown and render it as static

website, I was tired to always copy/paste same configuration accross all my

website, I was tired to always copy/paste same configuration accross all my

projects documentations.

project documentations.





Even worst, when I decide to change some minor things (such as color palettes),

Even worst, when I decide to change some minor things (such as color palettes),

I had to go to each projects and for each project I had to replace manually

I had to go to each project and for each project I had to replace manually

every time the same two configuration lines.

every time the same two configuration lines.





This project aims is to ease the management of documentation configuration by

This project aim is to ease the management of documentation configuration by

allowing to create a template and easily setup or upgrade it to a newer

allowing to create a template and easily setup or upgrade it to a newer

version.

version.
@@ -78,7 +78,7 @@ chmod +x /tmp/setup_mkdocs.sh 
```

```





Or if you already read the content of the script `setup.sh` at the root of this

Or if you already read the content of the script `setup.sh` at the root of this

repo, previous commands can be done in online:

repo, previous commands can be done in one line:





```

```

# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION

# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION
@@ -169,4 +169,4 @@ You can now browse the full documentation by visiting 




<!-- END MKDOCS TEMPLATE -->

<!-- END MKDOCS TEMPLATE -->





[online_doc]: https://docs.romaindeville.fr/rdeville.public/my_programs/mkdocs_template/index.html
 
[online_doc]: https://docs.romaindeville.fr/my_programs/mkdocs_template/index.html

docs/.gitlab-ci.yml

+28 −23
Original line number Original line Diff line number Diff line 




### BEGIN MKDOCS TEMPLATE ###

### BEGIN MKDOCS TEMPLATE ###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### Modified content will be overwritten when updating.###

### Modified content will be overwritten when updating.###
@@ -20,8 +22,8 @@ workflow: 
    # WIP, NO-CI or 🚧 (gitmoji for "work in progress", aka :construction:)

    # WIP, NO-CI or 🚧 (gitmoji for "work in progress", aka :construction:)

    - if: $CI_COMMIT_TITLE =~ /.*(WIP|NO-CI|🚧|:construction:).*/

    - if: $CI_COMMIT_TITLE =~ /.*(WIP|NO-CI|🚧|:construction:).*/

      when: never

      when: never

    # Run the CI otherwise (depending on `rules` key per jobs)

    # Do not run CI if repo is not on framagit

    - when: always

    - if: $CI_SERVER_HOST =~ /^framagit.org/





# Stages jobs will pass through with anchors to avoid updating stage in multiple

# Stages jobs will pass through with anchors to avoid updating stage in multiple

# place within this file. Now renaming a stage can be done directly after the

# place within this file. Now renaming a stage can be done directly after the
@@ -98,7 +100,7 @@ variables: 
        export RSYNC_DEST="${RSYNC_DEST}/pre_prod/"

        export RSYNC_DEST="${RSYNC_DEST}/pre_prod/"

        export ONLINE_DEST="${ONLINE_DEST}/pre_prod/"

        export ONLINE_DEST="${ONLINE_DEST}/pre_prod/"

      ;;

      ;;

      "pre_prod")

      "prod")

        export RSYNC_DEST="${RSYNC_DEST}/"

        export RSYNC_DEST="${RSYNC_DEST}/"

        export ONLINE_DEST="${ONLINE_DEST}/"

        export ONLINE_DEST="${ONLINE_DEST}/"

      ;;

      ;;
@@ -116,6 +118,8 @@ variables: 
  - &rules_regexp_dev $CI_COMMIT_BRANCH =~ /^((release|feature|hotfix|bugfix)-|merge_request_)*/

  - &rules_regexp_dev $CI_COMMIT_BRANCH =~ /^((release|feature|hotfix|bugfix)-|merge_request_)*/

  - &rules_regexp_pre_prod $CI_COMMIT_BRANCH =~ /(develop|master)/

  - &rules_regexp_pre_prod $CI_COMMIT_BRANCH =~ /(develop|master)/

  - &rules_regexp_prod $CI_COMMIT_TAG

  - &rules_regexp_prod $CI_COMMIT_TAG

  - &rules_regexp_trigger_main (($CI_COMMIT_BRANCH =~ /(develop|master)/) || $CI_COMMIT_TAG) && ($MAIN_PROJECT != null && $MAIN_PROJECT != $CI_PROJECT_PATH)

  - &rules_regexp_trigger_info (($CI_COMMIT_BRANCH =~ /(develop|master)/) || $CI_COMMIT_TAG) && $MAIN_PROJECT == null





# Defining rules that now replace only to run jobs under specific condition

# Defining rules that now replace only to run jobs under specific condition

# and define variables

# and define variables
@@ -134,6 +138,12 @@ variables: 
  variables:

  variables:

    CI_DEPLOY_TYPE: "prod"

    CI_DEPLOY_TYPE: "prod"





.rules_trigger_main: &rules_trigger_main

  if: *rules_regexp_trigger_main



.rules_trigger_info: &rules_trigger_info

  if: *rules_regexp_trigger_info



# Tag anchors

# Tag anchors

# -----------------------------------------------------------------------------

# -----------------------------------------------------------------------------

# https://docs.gitlab.com/ee/ci/yaml/README.html#tag

# https://docs.gitlab.com/ee/ci/yaml/README.html#tag
@@ -244,9 +254,9 @@ script_pre_test_ensure_variable: &script_pre_test_ensure_variable 
        return 1

        return 1

      fi

      fi

  rules:

  rules:

    - *rules_dev

    - *rules_pre_prod

    - *rules_prod

    - *rules_prod

    - *rules_pre_prod

    - *rules_dev





# Jobs in test stage

# Jobs in test stage

# -----------------------------------------------------------------------------

# -----------------------------------------------------------------------------
@@ -343,12 +353,15 @@ script_deploy_html: &script_deploy_html 
      esac

      esac

    - export RSYNC_PATH="${PROJECT_PATH}${LAST_TAG}"

    - export RSYNC_PATH="${PROJECT_PATH}${LAST_TAG}"

    - export ONLINE_PATH="${ONLINE_DEST}${PROJECT_PATH}latest"

    - export ONLINE_PATH="${ONLINE_DEST}${PROJECT_PATH}latest"

    - echo "$PROJECT_PATH"

    - mkdir -p "tmp/${RSYNC_PATH}"

    - mkdir -p "tmp/${RSYNC_PATH}"

    - mv site/* "tmp/${RSYNC_PATH}/"

    - mv site/* "tmp/${RSYNC_PATH}/"

    - |

      if [[ -f "tmp/${RSYNC_PATH}/versions.json" ]]

      then

        cp tmp/${RSYNC_PATH}/versions.json tmp/${RSYNC_PATH}/../versions.json

      fi

    - ln -s "${LAST_TAG}" "latest"

    - ln -s "${LAST_TAG}" "latest"

    - mv "latest" "tmp/${PROJECT_PATH}"

    - mv "latest" "tmp/${PROJECT_PATH}"

    - rsync -avz "tmp/" "${RSYNC_DEST}"

    - echo -e "

    - echo -e "

      <!DOCTYPE html>\n

      <!DOCTYPE html>\n

      <html>\n

      <html>\n
@@ -365,18 +378,12 @@ script_deploy_html: &script_deploy_html 
      <body>\n

      <body>\n

        Redirecting to <a href='${ONLINE_PATH}'>${ONLINE_PATH}</a>...\n

        Redirecting to <a href='${ONLINE_PATH}'>${ONLINE_PATH}</a>...\n

      </body>\n

      </body>\n

      </html>" > index.html

      </html>" > tmp/${PROJECT_PATH}/index.html

    - rsync -avz index.html "${RSYNC_DEST}${PROJECT_PATH}/"

    - rsync -Oavz "tmp/" "${RSYNC_DEST}"

    - |

      if [[ -f "site/versions.json" ]]

      then

        cp site/versions.json versions.json

        rsync -avz versions.json "${RSYNC_DEST}${PROJECT_PATH}/"

      fi

  rules:

  rules:

    - *rules_dev

    - *rules_pre_prod

    - *rules_prod

    - *rules_prod

    - *rules_pre_prod

    - *rules_dev





# Jobs in post_deploy stage

# Jobs in post_deploy stage

# -----------------------------------------------------------------------------

# -----------------------------------------------------------------------------
@@ -391,9 +398,7 @@ trigger_main_repo: 
  variables:

  variables:

    MAIN_PROJECT_CI_PATH: ${MAIN_PROJECT_CI_PATH:-"."}

    MAIN_PROJECT_CI_PATH: ${MAIN_PROJECT_CI_PATH:-"."}

  rules:

  rules:

    - *rules_pre_prod

    - *rules_trigger_main

    - *rules_prod

    - if: $MAIN_PROJECT && $MAIN_PROJECT != $CI_PROJECT_PATH





inform_triggers_variables:

inform_triggers_variables:

  <<: *tag_docker

  <<: *tag_docker
@@ -413,12 +418,12 @@ inform_triggers_variables: 
          INFO - the \`MAIN_PROJECT\`."

          INFO - the \`MAIN_PROJECT\`."

      fi

      fi

  rules:

  rules:

    - *rules_pre_prod

    - *rules_trigger_info

    - *rules_prod

    - if: ! $MAIN_PROJECT





# *****************************************************************************

# *****************************************************************************

# VIM MODELINE

# VIM MODELINE

# vim: fdm=indent

# vim: fdm=indent

# *****************************************************************************

# *****************************************************************************

### END MKDOCS TEMPLATE ###

### END MKDOCS TEMPLATE ###

docs/_data/extra.yaml

0 → 100644
+33 −0
Original line number Original line Diff line number Diff line 
# Minimal set of variable for subrepo example in usage/configure.md

example:

  my_repo_slug:

    name: My Main Repo Name

    desc: Description of my [Main Repo]()

  subrepo:

    roles:

      nav_entry: "Roles"

      internal:

        - name: role_name_1

        - name: role_name_2

      external:

        - name: my_first_role

    programs:

      nav_entry: "My Programs"

      external:

        - name: my_first_repo

        - name: my_second_repo

role_name_1:

  name: Role Name 1

  desc: Description of the Role Name 1

role_name_2:

  name: Role Name 2

  desc: Description of the Role Name 2

my_first_role:

  name: My First Role

  desc: Description of My First Role

my_first_repo:

  name: My First Repo

  desc: Description of My First Repo

my_second_repo:

  name: My Second Repo

  desc: Description of My Second Repo

docs/_data/plugins.py

+76 −42
Original line number Original line Diff line number Diff line 
#!/usr/bin/env python3

#!/usr/bin/env python3

"""

"""Set of methods to manage mkdocs configuration dynamically.



Set of methods for

Set of methods for

[mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) Set of

[mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) Set of

which :

which :
@@ -152,6 +153,10 @@ def add_external_to_nav( 
                        repo_parent,

                        repo_parent,

                        nav_parent[1:],

                        nav_parent[1:],

                    )

                    )

    elif repo_dict["online_url"].startswith('/'):

        nav.append({

            repo_dict["nav_entry"]: repo_dict["online_url"].replace('/','../',1)

        })

    else:

    else:

        nav.append({repo_dict["nav_entry"]: repo_dict["online_url"]})

        nav.append({repo_dict["nav_entry"]: repo_dict["online_url"]})
@@ -400,9 +405,19 @@ def set_copyright(env: dict, git_repo: git.Repo) -> None: 
            first_year = time.strftime("%Y", time.localtime())

            first_year = time.strftime("%Y", time.localtime())

        curr_year = time.strftime("%Y", time.localtime())

        curr_year = time.strftime("%Y", time.localtime())





        if first_year == curr_year:

            env.variables[

                "date_copyright"

            ] = f"Copyright &copy; {curr_year}"

        else:

            env.variables[

                "date_copyright"

            ] = f"Copyright &copy; {curr_year} - {curr_year}"



        env.conf[

        env.conf[

            "copyright"

            "copyright"

        ] = f"Copyright &copy; {first_year} - {curr_year} {env.variables['copyright']}"

        ] = f"{env.variables['date_copyright']} {env.variables['copyright']}"











def set_repo_name(env: dict, repo_slug: str) -> None:

def set_repo_name(env: dict, repo_slug: str) -> None:
@@ -424,7 +439,6 @@ def set_repo_name(env: dict, repo_slug: str) -> None: 
        env: Mkdocs macro plugin environment dictionary.

        env: Mkdocs macro plugin environment dictionary.

        repo_slug: Repo slug or name of the repo folder.

        repo_slug: Repo slug or name of the repo folder.

    """

    """



    if "repo_name" not in env.conf or not env.conf["repo_name"]:

    if "repo_name" not in env.conf or not env.conf["repo_name"]:

        if "repo_name" in env.variables:

        if "repo_name" in env.variables:

            env.conf["repo_name"] = env.variables["repo_name"]

            env.conf["repo_name"] = env.variables["repo_name"]
@@ -533,7 +547,6 @@ def set_config(env: dict) -> None: 
    Arguments:

    Arguments:

        env: Mkdocs macro plugin environment dictionary.

        env: Mkdocs macro plugin environment dictionary.

    """

    """



    git_repo = git.Repo(search_parent_directories=True)

    git_repo = git.Repo(search_parent_directories=True)

    repo_slug = get_repo_slug(env, git_repo)

    repo_slug = get_repo_slug(env, git_repo)
@@ -557,7 +570,7 @@ def set_config(env: dict) -> None: 








def load_yaml_file(path: str, filename: str) -> None:

def load_yaml_file(path: str, filename: str) -> None:

    """Ensure a YAML file is valid again a schema and return its content

    """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

    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.

    validate its content. If content is not valid, an error will be raised.
@@ -602,7 +615,7 @@ def update_subrepo_logo_src( 
    path: str,

    path: str,

    external: bool,

    external: bool,

) -> None:

) -> None:

    """Update the content of the key `logo` and `src_path` of subrepo

    """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

    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

    from file `docs/_data/repo.yaml` in the cloned subrepo, relative to the main
@@ -740,7 +753,7 @@ def update_subrepo( 
def update_logo_src_repo(

def update_logo_src_repo(

    env: dict, curr_repo: dict, repo_name: str, path: str = None

    env: dict, curr_repo: dict, repo_name: str, path: str = None

) -> None:

) -> None:

    """Update the content of the key `logo` and `src_path` of current repo

    """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

    Update value of keys `logo` and `src_path` of current repo holding the

    documentation.

    documentation.
@@ -753,7 +766,6 @@ def update_logo_src_repo( 
        repo_name: Name of the repo,

        repo_name: Name of the repo,

        path: Absolute path of the location of the current repo.

        path: Absolute path of the location of the current repo.

    """

    """



    subpath = ""

    subpath = ""

    if path:

    if path:

        subpath = os.path.join(path.replace(env.project_dir, ""), repo_name)

        subpath = os.path.join(path.replace(env.project_dir, ""), repo_name)
@@ -771,7 +783,7 @@ def update_logo_src_repo( 








def load_var_file(env: dict) -> None:

def load_var_file(env: dict) -> None:

    """Load variables files in `docs/_data/`

    """Load variables files in `docs/_data/`.





    Load every yaml files in `docs/_data/`, if one of the file define the

    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.

    current repo, then update keys `logo` and `src_path` for the current repo.
@@ -792,7 +804,7 @@ def load_var_file(env: dict) -> None: 








def update_version(env: dict) -> None:

def update_version(env: dict) -> None:

    """Parse every tags of the repo to build a `docs/versions.json`

    """Parse every tags of the repo to build a `docs/versions.json`.





    To emulate mike version support for gitlab, this method will parse every

    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

    tags of the current repo holding the current documentation to create a file
@@ -812,45 +824,51 @@ def update_version(env: dict) -> None: 
        return

        return

    git_repo = git.Repo(search_parent_directories=True)

    git_repo = git.Repo(search_parent_directories=True)

    mike_version = list()

    mike_version = list()

    last_major = 0

    last_major = -1

    last_minor = 0

    last_minor = -1

    last_patch = 0

    last_patch = str(-1)

    for i_tag in git_repo.tags:

    for i_tag in git_repo.tags:

        i_tag = yaml.dump(i_tag.path)

        i_tag = yaml.dump(i_tag.path)

        i_tag = re.sub(".*v", "", i_tag).split(".")

        i_tag = re.sub(".*v", "", i_tag).split(".")

        major = int(i_tag[0])

        major = int(i_tag[0])

        minor = int(i_tag[1])

        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 major > last_major:

            if last_major >= 0:

                mike_version.append(

                mike_version.append(

                    {

                    {

                    "version": "{}.{}".format(last_major, last_minor),

                        "version": f"{last_major}.{last_minor}",

                    "title": "{}.{}.{}".format(

                        "title": f"{last_major}.{last_minor}.{last_patch}",

                        last_major, last_minor, last_patch

                    ),

                        "aliases": [],

                        "aliases": [],

                    }

                    }

                )

                )

            last_major = major

            last_major = major

            last_minor = 0

            last_minor = -1

        if minor > last_minor:

        if minor > last_minor:

            if last_minor >= 0:

                mike_version.append(

                mike_version.append(

                    {

                    {

                    "version": "{}.{}".format(last_major, last_minor),

                        "version": f"{last_major}.{last_minor}",

                    "title": "{}.{}.{}".format(

                        "title": f"{last_major}.{last_minor}.{last_patch}",

                        last_major, last_minor, last_patch

                    ),

                        "aliases": [],

                        "aliases": [],

                    }

                    }

                )

                )

            last_minor = minor

            last_minor = minor

            last_patch = 0

            last_patch = str(-1)

        if patch > last_patch:

        if patch > last_patch:

            last_patch = patch

            last_patch = str(patch)



    mike_version.append(

    mike_version.append(

        {

        {

            "version": "{}.{}".format(last_major, last_minor),

            "version": f"{last_major}.{last_minor}",

            "title": "{}.{}.{}".format(last_major, last_minor, last_patch),

            "title": f"{last_major}.{last_minor}.{last_patch}",

            "aliases": ["latest"],

            "aliases": ["latest"],

        }

        }

    )

    )
@@ -864,7 +882,8 @@ def update_version(env: dict) -> None: 
def define_env(env: dict) -> None:

def define_env(env: dict) -> None:

    # pylint: disable=C0301

    # pylint: disable=C0301

    # - C0301: Line to long

    # - C0301: Line to long

    """

    """Hook for mkdocs-macros-plugins defining variables, macros and filters.



    This is the hook for defining variables, macros and filters

    This is the hook for defining variables, macros and filters





    - variables: the dictionary that contains the environment variables

    - variables: the dictionary that contains the environment variables
@@ -879,7 +898,6 @@ def define_env(env: dict) -> None: 
    Arguments:

    Arguments:

        env: Mkdocs macro plugin environment dictionary.

        env: Mkdocs macro plugin environment dictionary.

    """

    """



    load_var_file(env)

    load_var_file(env)





    if "subrepo" in env.variables:

    if "subrepo" in env.variables:
@@ -898,14 +916,30 @@ def define_env(env: dict) -> None: 
    # pylint: disable=W0612

    # pylint: disable=W0612

    # -  W0612: Unused variable (unused-variable)

    # -  W0612: Unused variable (unused-variable)

    def subs(var: str) -> dict:

    def subs(var: str) -> dict:

        """Return the content of the dictionary defined by var"""

        """Return the content of the dictionary defined by var.



        Arguments:

            var: Key in env.variables to return.



        Returns:

            The value of `env.variables[var]` if it exists, else return None.

        """

        if var in env.variables:

            return env.variables[var]

            return env.variables[var]

        return None





    @env.macro

    @env.macro

    # pylint: disable=W0612

    # pylint: disable=W0612

    # -  W0612: Unused variable (unused-variable)

    # -  W0612: Unused variable (unused-variable)

    def to_html(var: str) -> dict:

    def to_html(var: str) -> dict:

        """Convert the content of the markdown string into HTML"""

        """Convert the content of the markdown string into HTML.



        Arguments:

            var: Markdown string which need to be converted to HTML



        Returns:

            The content of the markdown converted to HTML

        """

        return markdown.markdown(var)

        return markdown.markdown(var)

docs/_data/template/repo.tpl.yaml

+7 −3
Original line number Original line Diff line number Diff line 


### BEGIN MKDOCS TEMPLATE ###

### BEGIN MKDOCS TEMPLATE ###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### Modified content will be overwritten when updating.###

### 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

  # (OPTIONAL) Path, relative to `docs_dir` mkdocs config, to the logo of the

  # repo. If not specified, path will automatically be set to

  # repo. If not specified, path will automatically be set to

  # `assets/img/meta/reop_name_logo.png`

  # `assets/img/meta/repo_name_logo.png`

  #logo: "assets/img/meta/repo_template_logo.png"

  #logo: "assets/img/meta/repo_name_logo.png"

  # Description of the repo, will be used to setup the mkdocs description.

  # Description of the repo, will be used to setup the mkdocs description.

  desc: >-

  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

  # (OPTIONAL) If you plan to use `mkdocstring` plugins to render python

  # source code, you will need to provide the path where your source files

  # source code, you will need to provide the path where your source files
@@ -47,3 +50,4 @@ repo_name: 
    - name: "Firstname Lastname"

    - name: "Firstname Lastname"

      mail: "mail@domain.tld"

      mail: "mail@domain.tld"

### END MKDOCS TEMPLATE ###

### END MKDOCS TEMPLATE ###

docs/_data/template/subrepo.tpl.yaml

+10 −0
Original line number Original line Diff line number Diff line 


### BEGIN MKDOCS TEMPLATE ###

### BEGIN MKDOCS TEMPLATE ###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### Modified content will be overwritten when updating.###

### Modified content will be overwritten when updating.###
@@ -25,6 +26,10 @@ subrepo: 
  #     - name: subrepo_1

  #     - name: subrepo_1

  #       # SSH or HTTP link to the online subrepo_1

  #       # SSH or HTTP link to the online subrepo_1

  #       git_url: git@domain.tld:namesapce/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

  #   # List of subdirectory from `dir_name` which are repos with

  #   # mkdocs documentation which will be included in the documentation.

  #   # mkdocs documentation which will be included in the documentation.

  #   external:

  #   external:
@@ -34,6 +39,10 @@ subrepo: 
  #     - name: subrepo_2

  #     - name: subrepo_2

  #       # SSH or HTTP link to the online subrepo_2

  #       # SSH or HTTP link to the online subrepo_2

  #       git_url: git@domain.tld:namesapce/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

  #   # Another sub dir_name which also old subrepos

  #   subdir_name:

  #   subdir_name:

  #     nav_entry: "Sub Nav Entry"

  #     nav_entry: "Sub Nav Entry"
@@ -75,3 +84,4 @@ subrepo: 
  #     - Mkdocs Template: /my_program/mkdocs_template/

  #     - Mkdocs Template: /my_program/mkdocs_template/

  # ```

  # ```

### END MKDOCS TEMPLATE ###

### END MKDOCS TEMPLATE ###

docs/_data/vars.yaml

+5 −1
Original line number Original line Diff line number Diff line 




### BEGIN MKDOCS TEMPLATE ###

### BEGIN MKDOCS TEMPLATE ###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### Modified content will be overwritten when updating.###

### Modified content will be overwritten when updating.###
@@ -27,7 +29,7 @@ 
# The name or company which old the copyright. No need to specify any date

# 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,

# 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.

# then no copyright will be shown on the footer of the documentation.

#copyright: "Firstname Lastname"

copyright: "Romain Deville"





# Name of your repo, if not specified, will be the key `mkdocs_repo_name` in

# 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

# `_data/repo_name.yaml` If value is EXACTLY "!!git_platform", then the value
@@ -93,3 +95,5 @@ git_platform: 
  # configuration.

  # configuration.

  url: "https://framagit.org/"

  url: "https://framagit.org/"

### END MKDOCS TEMPLATE ###

### END MKDOCS TEMPLATE ###

docs/about/contributing.md

+5 −3
Original line number Original line Diff line number Diff line 
{% set curr_repo=subs("mkdocs_template") %}

{% set curr_repo=subs("mkdocs_template") %}







<!-- BEGIN MKDOCS TEMPLATE -->

<!-- BEGIN MKDOCS TEMPLATE -->

<!--

<!--

WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !

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

  * [Contributing workflow][contributing_workflow], which provide an example

   of the workflow I used for the development.

   of the workflow I used for the development.





[developers_guides]: {{ site_base_url }}/dev_guides/index.html

[developers_guides]: {{ site_base_url }}/latest/dev_guides/index.html

[syntax_guide]: {{ site_base_url }}/dev_guides/style_guides/index.html

[syntax_guide]: {{ site_base_url }}/latest/dev_guides/style_guides/index.html

[contributing_workflow]: {{ site_base_url }}/dev_guides/contributing_workflow.html

[contributing_workflow]: {{ site_base_url }}/latest/dev_guides/developer_guidelines.html





## Community

## Community
@@ -52,3 +53,4 @@ conduct][code_of_conduct]. 
[code_of_conduct]: code_of_conduct.md

[code_of_conduct]: code_of_conduct.md





<!-- END MKDOCS TEMPLATE -->

<!-- END MKDOCS TEMPLATE -->

docs/about/license.md

+1 −1
Original line number Original line Diff line number Diff line
@@ -17,7 +17,7 @@ Software is under double licensing: 




## MIT License

## MIT License





Copyright (c) 2020

{{ date_copyright }}





{% for i_maintainer in curr_repo.maintainers %}

{% for i_maintainer in curr_repo.maintainers %}

  - [{{ i_maintainer.name }}](mailto:{{ i_maintainer.mail }})

  - [{{ i_maintainer.name }}](mailto:{{ i_maintainer.mail }})

docs/about/release_notes.md

+43 −0
Original line number Original line Diff line number Diff line
@@ -8,3 +8,46 @@ Modified content will be overwritten when updating 




<!-- END MKDOCS TEMPLATE -->

<!-- END MKDOCS TEMPLATE -->





## 🔖 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

- ✨ Improve handling of copyright in plugins.py script

- 🔥 Remove useless file from tracked tree



### 🔖 v1.0.1 <small>(29/04/2021)</small>



- 🐛🍱 Fix wrong assets path in `docs/personal_template/create.md`

- 🐛 Update `plugins.py` to latest release



### 🔖 v1.0.0 <small>(29/04/2021)</small>



First initial release of MkDocs Template



- ✨ Add bunch of features:

    - `setup.sh` script to automatically install template,

    - `template` folder holding basic template files, script

      `docs/_data/plugins.py` to dynamically setup `mkdocs.yml` configuration

      and schema and template for files read by the script

- 🔧 Add bunch of configuration files:

    - Syntax and workflow configuration files such as `.editorconfig`,

      `.yamllint`, `pyproject.toml`

- 👷 Add CI which test the scripts (bash and python), build the

  documentation and deploy it

- 📝🍱 Add the documentation describing the usage of the template with needed

  assets.

- 📄 Add licenses, MIT and Beer-Ware.

docs/index.md

+76 −0
Original line number Original line Diff line number Diff line
@@ -42,3 +42,79 @@ platforms. 
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------





<!-- END MKDOCS TEMPLATE -->

<!-- END MKDOCS TEMPLATE -->



## Introduction



Since some times now, I use [mkdocs][mkdocs] to write documentation of my

projects.



While [mkdocs][mkdocs] is a really usefull software allowing me to write clean

and clear documentation in markdown and render it as static website, I was tired

to always copy/paste same configuration accross all my projects documentations.



Even worst, when I decide to change some minor things (such as color palettes),

I had to go to each projects and for each project I had to replace manually

every time the same two configuration lines.



This project aims is to ease the management of documentation configuration by

allowing to create a template and easily setup or upgrade it to a newer version.



## Usage



Below is a really basic usage example of this repo, more complete documentation

is provided at section [Use Template][use_template] and if you want to create

your own template from this repo, you can refer to the section [Setup Your Own

Template][setup_your_own_template]



Assuming you want to use this **really** basic template. In a repo in which you

want to create a documentation, type the following commands:



```bash

# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION

# First download the setup script into a temporary folder

wget {{ git_platform.url }}{{ curr_repo.repo_path_with_namespace }}/-/raw/master/setup.sh \

   -O /tmp/setup_mkdocs.sh

# Then read the content of the script with your favorite editor

vim /tmp/setup_mkdocs.sh

# If you are confident with what the script does, make it executable and run it

chmod +x /tmp/setup_mkdocs.sh

/tmp/setup_mkdocs.sh -r {{ git_platform.url }}{{ curr_repo.repo_path_with_namespace }}

```



Or if you already read the content of the script `setup.sh` at the root of this

repo, previous commands can be done in online:



```bash

# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION

# You can get the content of the script setup.sh via curl and pipe it into bash

curl -sfL {{ git_platform.url }}{{ curr_repo.repo_path_with_namespace }}/-/raw/master/setup.sh \

   | bash -s -- -r {{ git_platform.url }}{{ curr_repo.repo_path_with_namespace }}

```



This will automatically create the folder `docs` with basic pages and the

following files:



- `mkdocs.yml`

- `requirements.docs.in`

- `requirements.docs.txt`



What you will now have to do is :



- Copy the provided template file `docs/_data/template/repo.tpl.yaml` into

  `docs/_data/repo_name.yml` such as `repo_name` is the slug of your repo (for

  instance slug of `mkdocs template` is `mkdocs_template` and slug of

  `docs.domain.tld project` is `docs_domain_tld_project`).

- Edit this new file `docs/_data/repo_name.yml`, especially, do not forget to

  change the key `repo_name` in the file accordingly to your repo slug.



You are ready now to render you documentation:



```bash

mkdocs serve

```



[use_template]: usage/

[setup_your_own_template]: personal_template



<!-- URL used in mulitple section -->

[mkdocs]: https://mkdocs.org/

docs/personal_template/create.md

0 → 100644
+467 −0
Original line number Original line Diff line number Diff line 
{% set curr_repo=subs("mkdocs_template") %}

# Create Custom Template



## Fork the main repo



!!! info



    Only forking from [Mkdocs Template Repo][mkdocs_template_repo] on {{

    git_platform.name }} will be described here. If you find a mirror of this

    repo, you can still fork this mirror but documentation of such process will

    not be presented here.



First thing to do is to fork the [Mkdocs Template Repo][mkdocs_template_repo].

To do so, click on the button ++"燎 Fork"++ as shown below:



![!Fork Mkdocs Template][fork_mkdocs_template]



Then, choose where you want to store your fork in one of your accessible

namespaces:



![!Fork Mkdocs Template Destination][fork_mkdocs_template_dest]



Wait for the fork to finish:



![!Fork Mkdocs Template Finish][fork_mkdocs_template_finish]



Finally, you can clone your forked.



!!! note



    In the rest of documentation we will assume you forked the main repo to

    https://gitdomain.tld/namespace/mkdocs_template.git.



```bash

# Clone using https

git clone https://gitdomain.tld/namespace/mkdocs_template.git.

# Clone using ssh

git clone git@gitdomain.tld:namespace/mkdocs_template.git.

```



[mkdocs_template_repo]: {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}

[fork_mkdocs_template]: ../assets/img/fork_main_repo.png

[fork_mkdocs_template_dest]: ../assets/img/fork_dest_namespace.png

[fork_mkdocs_template_finish]: ../assets/img/fork_finish.png



## Add the content of your template



Now, to setup your own template, you just have to write it in the empty, but

tracked, folder `user_config`. If you happen to add a file with the same

path from `template`, then your file will override the one in `template`.



For instance, if you create a file `user_config/docs/index.md`, its content will

override the content of the file `template/docs/index.md` when using template.



Moreover, you can add a `post_setup.sh` script in `user_config` to handle

customized command once `setup.sh` finish. The script `post_setup.sh` will be

automatically included at the end of the execution of the script `setup.sh`.



Below are some examples, such as a possible structure of `user_config` folder as

well as some content examples. Note that every files, hidden or not, within

folder `user_config` are copied when installed, which can be usefull to provide

configuration workflow files, such as `.editorconfig`, `.gitignore`, etc.



=== "Folder `user_config`"



    ```text

    ├──  .editorconfig

    ├──  .gitignore

    ├──  .gitkeep

    ├──  .gitlab-ci.yml

    ├──  .yamllint

    ├──  docs

    │  ├──  .gitlab-ci.yml

    │  ├──  _data

    │  │  └──  vars.yaml

    │  ├──  about

    │  │  ├──  code_of_conduct.md

    │  │  ├──  contributing.md

    │  │  ├──  data_privacy.md

    │  │  ├──  index.md

    │  │  ├──  license.md

    │  │  └──  release_notes.md

    │  ├──  index.md

    │  └──  theme

    │     ├──  css

    │     │  └──  theme.css

    │     └──  js

    │        └──  extra.js

    ├──  LICENSE.BEERWARE

    ├──  LICENSE.MIT

    ├──  mkdocs.local.yml

    ├──  post_setup.sh

    ├──  pyproject.toml

    ├──  README.md

    ├──  requirements.dev.in

    ├──  requirements.dev.txt

    ├──  requirements.docs.in

    └──  requirements.docs.txt

    ```



=== "`README.md`"



    Below is the templated content of a README.md which is automatically updated

    with the script `post_setup.sh`



    ````markdown

    <div align="center" style="text-align: center;">



      <!-- Project Title -->

      <a href="<TPL:REPO_URL>">

        <img src="docs/assets/img/meta/<TPL:REPO_NAME>_logo.png" width="100px">

        <h1><TPL:REPO_NAME_FIRST_UPPERCASE></h1>

      </a>



      <!-- Project Badges -->

      [![License][license_badge]][license]

      [![Build Status][build_status_badge]][build_status]



    --------------------------------------------------------------------------------



    TODO: Short description as written in `docs/_data/repo.yaml`



    --------------------------------------------------------------------------------



      <b>

    IMPORTANT !



    Main repo is on [ Framagit][repo_url].<br>

    On other online git platforms, they are just mirror of the main repo.<br>

    Any issues, pull/merge requests, etc., might not be considered on those other

    platforms.

      </b>

    </div>



    --------------------------------------------------------------------------------



    [repo_url]: <TPL:REPO_URL>

    [license_badge]: https://img.shields.io/badge/License-MIT%2FBeer%20Ware-blue?style=flat-square&logo=open-source-initiative

    [license]: LICENSE

    [build_status_badge]: <TPL:REPO_URL>/badges/master/pipeline.svg?style=flat-square&logo=appveyor

    [build_status]: <TPL:REPO_URL>/commits/master



    ## Table of Content



    * [Project Documentation](#project-documentation)



    <!-- BEGIN MKDOCS TEMPLATE -->

    <!--

         WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !

         Modified content will be overwritten when updating

    -->



    ## Project Documentation



    The complete documentation of the project can be accessed via its [Online

    Documentation][online_doc].



    If, for any reason, the link to the [Online Documentation][online_doc] is

    broken, you can generate its documention locally on your computer (since the

    documentation is jointly stored within the repository).



    To do so, you will need the following requirements:



      - Python >= 3.8

      - Pip3 with Python >= 3.8



    First setup a temporary python virtual environment and activate it:



    ```bash

    # Create the temporary virtual environment

    python3 -m venv .temporary_venv

    # Activate it

    source .temporary_venv/bin/activate

    ```



    Now, install required dependencies to render the documentation using

    [mkdocs][mkdocs] in the python virtual environment:



    ```bash

    pip3 install -r requirements.docs.txt

    ```



    Now you can easily render the documentation using [mkdocs][mkdocs] through the

    usage of the following command (some logs will be outputed to stdout):



    ```bash

    # Assuming you are at the root of the repo

    # If there is a `mkdocs.local.yml`

    mkdocs serve -f mkdocs.local.yml

    # If there is no `mkdocs.local.yml`, only `mkdocs.yml`

    mkdocs serve

    ```



    You can now browse the full documentation by visiting

    [http://localhost:8000][localhost].



    [localhost]: https://localhost:8000

    [mkdocs]: https://www.mkdocs.org/



    <!-- END MKDOCS TEMPLATE -->



    [online_doc]: <TPL:REPO_ONLINE_DOC_URL>/index.html

    ```

    ````



=== "`docs/theme/js/extra.js`"



    ```javascript

    /*

     * LIGHTGALLERY

     * ----------------------------------------------------------------------------

     * Lightgallery extra javascript

     * From: https://github.com/g-provost/lightgallery-markdown

     */



    /*

     * Loading lightgallery

     */

    var elements = document.getElementsByClassName("lightgallery");

    for(var i=0; i<elements.length; i++) {

      lightGallery(elements[i]);

    }



    /*

     * Loading video plugins for lightgallery

     */

    lightGallery(document.getElementById('html5-videos'));



    /*

     * Loading parameter to auto-generate thumbnails for vimeo/youtube video

     */

    lightGallery(document.getElementById('video-thumbnails'), {

        loadYoutubeThumbnail: true,

        youtubeThumbSize: 'default',

        loadVimeoThumbnail: true,

        vimeoThumbSize: 'thumbnail_medium',

    });



    /*

     * Table Sort

     * ----------------------------------------------------------------------------

     * Code snippet to allow sorting table

     * From: https://squidfunk.github.io/mkdocs-material/reference/data-tables/#sortable-tables

     */

    document$.subscribe(function() {

      var tables = document.querySelectorAll("article table")

      tables.forEach(function(table) {

        new Tablesort(table)

      })

    })





    /*

     * Mermaid Configuration to support dark/light switching

     * ----------------------------------------------------------------------------

     * Table Sort

     * Optional config

     * If your document is not specifying `data-md-color-scheme` for color schemes

     * you just need to specify `default`.

     */

    window.mermaidConfig = {

      "rdeville-light": {

        startOnLoad: false,

        theme: "default",

        flowchart: {

          htmlLabels: false

        },

        er: {

          useMaxWidth: false

        },

        sequence: {

          useMaxWidth: false,

          /*

           * Mermaid handles Firefox a little different. For some reason, it

           * doesn't attach font sizes to the labels in Firefox. If we specify the

           * documented defaults, font sizes are written to the labels in Firefox.

           */

          noteFontWeight: "14px",

          actorFontSize: "14px",

          messageFontSize: "16px"

        }

      },

      "rdeville-dark": {

        startOnLoad: false,

        theme: "dark",

        flowchart: {

          htmlLabels: false

        },

        er: {

          useMaxWidth: false

        },

        sequence: {

          useMaxWidth: false,

          noteFontWeight: "14px",

          actorFontSize: "14px",

          messageFontSize: "16px"

        }

      }

    }

    ```



=== "`docs/about/contributing.md`"



    ```markdown

    {% raw %}

    {% set curr_repo=subs("TODO") %}



    <!-- BEGIN MKDOCS TEMPLATE -->

    <!--

    WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !

    Modified content will be overwritten when updating

    -->



    # Contributing



    This project welcomes contributions from developers and users in the open source

    community. Contributions can be made in a number of ways, a few examples are :



      * Code patch via pull requests

      * Documentation improvements

      * Bug reports and patch reviews

      * Proposition of new features

      * etc.



    ## Reporting an Issue



    Please include as much details as you can when reporting an issue in the [issue

    trackers][issue_tracker]. If the problem is visual (for instance, wrong

    documentation rendering) please add a screenshot.



    [issue_tracker]: {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/issues



    ## Submitting Pull Requests



    Once you are happy with your changes or you are ready for some feedback, push it

    to your fork and send a pull request. For a change to be accepted it will most

    likely need to have tests and documentation if it is a new feature.



    For more information, you can refers to the main [developers

    guides][developers_guides] which is the common resources I use for all

    my projects. There you will find:



      * [Syntax Guide][syntax_guide], which describe syntax guidelines per language

        to follow if you want to contribute.

      * [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



    ## Community



    Finally, every member of the community should follow this [Code of

    conduct][code_of_conduct].



    [code_of_conduct]: code_of_conduct.md



    <!-- END MKDOCS TEMPLATE -->

    {% endraw %}

    ```





## Preview your template



When working on your custom template you might want to see a preview of your

template. To do so, simply call the script `preview.sh`



```bash

# Assuming you are at the root of the mkdocs template repo

./preview.sh

```



!!! note



    You might need to do so more command, such as copying repo file do

    `preview/docs/_data/mkdocs_template.yaml` or more. This will be prompted as

    error or warning when rendering preview.



This will compute the final list of files that will be installed, i.e. the union

of content of `template` and `user_config` folder, such that content of

`user_config` override content of `template`. Then create a symlink to each

final file in `preview` folder. Finally, render the documentation to

[http://localhost:8000][localhost]



[localhost]: http://localhost:8000



## Keep track with the main repo



If you want to update your fork to have the last version of the main repo, you

will first need to add a remote pointing to the main repo on

[{{ git_platform.name }}][repo_url].



First, list the current remote to ensure that remote `upstream` does not exists

yet:



```bash

git remote -v

> origin <URL_TO_YOUR_ORIGIN_REMOTE> (fetch)

> origin <URL_TO_YOUR_ORIGIN_REMOTE> (push)

```



If there is no `upstream`, add the `upstream` remote:



```bash

git remote add upstream {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}.git

```



Ensure that the remote upstream is well sets:



```bash

git remote -v

> origin <URL_TO_YOUR_ORIGIN_REMOTE> (fetch)

> origin <URL_TO_YOUR_ORIGIN_REMOTE> (push)

> upstream {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}.git (fetch)

> upstream {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}.git (push)

```



Once done, fetch branches from this `upstream` remote, commit to `master` of

the main repo will be stored in local branch `upstream/master`:



```text

git fetch upstream

> remote: Counting objects: 75, done.

> remote: Compressing objects: 100% (53/53), done.

> remote: Total 62 (delta 27), reused 44 (delta 9)

> Unpacking objects: 100% (62/62), done.

> From {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}.git

>  * [new branch]      master     -> upstream/master*

```



Check out your fork's local `master` branch.



```text

git checkout master

> Switched to branch 'master'

```



Merge the changes from `upstream/master` into your local `master` branch. This

brings your fork's `master` branch into sync with the `upstream` repository,

without losing your local changes.



```text

git merge upstream/master

> Updating a422352..5fdff0f

> Fast-forward

>  README                    |    9 -------

>  index.md                  |    7 ++++++

>  2 files changed, 7 insertions(+), 9 deletions(-)

>  delete mode 100644 README

>  create mode 100644 index.md

```



If your local branch didn't have any unique commits, Git will instead perform a

"fast-forward":



```text

git merge upstream/master

> Updating 34e91da..16c56ad

> Fast-forward

>  index.md                 |    5 +++--

>  1 file changed, 3 insertions(+), 2 deletions(-)

```



Here you are up-to-date with the main repo :wink:.



[repo_url]: {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}

docs/personal_template/example.md

0 → 100644
+36 −0
Original line number Original line Diff line number Diff line 
{% set curr_repo=subs("mkdocs_template") %}

# Example



The current documentation you are reading is actually using the custom template

[Mkdocs Template R.Deville][mkdocs_template_rdeville].



This custom template add a lots of things such as :



  - `.gitlab-ci.yaml` with basic CI file at the root of the repo to later be

    extended and another CI file to only test and build the documentation,

  - Workflow files definining some syntax rules such as `.editorconfig`,

    `.yamllint`, `pyproject.toml` (which also define basic test using `tox`),

  - `README.md`, a template of README which is automatically updated with the

    script `post_setup.sh`,

  - `mkdocs.yml` with more plugins and more configuration than the basic file.

  - A default `docs/_data/vars.yaml` file,

  - A complete theme using new plugins defined in `mkdocs.yml` with custom CSS,

    javascript, images, etc.,

  - A predefined basic `docs` content,

  - And many more things.



Below is an example of the rendering of the preview of the basic template and

the custom template.



=== "Basic Template"



    ![!Basic Template Preview][basic_template_preview]



=== "Custom Template"



    ![!Custom Template Preview][custom_template_preview]



[mkdocs_template_rdeville]: {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}_rdeville

[basic_template_preview]: ../assets/img/basic_template_preview.png

[custom_template_preview]: ../assets/img/custom_template_preview.png

docs/personal_template/index.md

0 → 100644
+25 −0
Original line number Original line Diff line number Diff line 
# Setup Your Own Template



As you may have seen, the usage of this repo install a **really** basic

template, with little to no configuration, neither extra content such as extra

JS nor CSS.



But, you may want to use extra plugins such as

[mkdocs-mermaid2-plugin][mkdocs_mermaid2_plugin] or provide a basic `README.md`

as well as licenses or a default file `docs/_data/vars.yml` for all your

documentation.



To do so, you will need to create your own template and use it. To learn how to

do, see:



- [Create your own template][create_custom_template]

- [Use your own template][use_custom_template]



Finally, you can see the [Example custom template][example_custom_template] to

give you hint about what can be done.





[mkdocs_mermaid2_plugin]: https://github.com/fralau/mkdocs-mermaid2-plugin

[create_custom_template]: create.md

[use_custom_template]: usage.md

[example_custom_template]: example.md

docs/personal_template/usage.md

0 → 100644
+90 −0
Original line number Original line Diff line number Diff line 
{% set curr_repo=subs("mkdocs_template") %}

# Use Your Custom Template



!!! note



    In the rest of documentation we will assume you forked the main repo to

    https://gitdomain.tld/namespace/mkdocs_template.git.



Now you have created your custom template you might want to use it. Well it is

as simple as installing the mkdocs template from the main repo. This is done

using the script the `setup.sh`. Below is a recall of the script usage.



{% include "docs/usage/setup.sh.md" %}



## Installing your own template



Similarly to the installation of the main template, to install your custom

template, you will need to download the `setup.sh` script. Note that you can

download it either from your fork (not recommended) or from the main repo, which

is the recommended way to ensure having the latest `setup.sh`.



The main difference with the installation of your own template compared to the

installation of the basic main template is the url of the repo to use.



```bash

# Assuming you are in the repo for which you want to write a documentation

# First download the setup script into a temporary folder

wget {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \

   -O /tmp/setup_mkdocs.sh

# Then read the content of the script with your favorite editor

vim /tmp/setup_mkdocs.sh

# If you are confident with what the script does, make it executable and run it

chmod +x /tmp/setup_mkdocs.sh

# Note the URL of the repo specified with option `-r`

/tmp/setup_mkdocs.sh -r https://gitdomain.tld/namespace/mkdocs_template.git

```



Or if you already read the content of the script `setup.sh` at the root of this

repo, previous commands can be done in online:



```bash

# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION

# You can get the content of the script setup.sh via curl and pipe it into bash

curl -sfL \

  {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \

  | bash -s -- \

    -r https://gitdomain.tld/namespace/mkdocs_template.git

```



This will automatically compute the union of the content of the folder

`templates` and the folder `user_config` and copy them in the folder where you

are located.



## Upgrade from your template



Later, you may change some configuration in your template, such as adding or

removing files, updating CSS, etc. Once this modification done, you will need to

upgrade your already installed documentation from your new template.



This is done by using the option `-u` of the script `setup.sh`. Using this

option, the script will compare last version with old version of each files, if

they have changed, backup the old version, to avoid losing content in case of error

and then upgrade the files to the latest version.



```bash

# Assuming you are in the repo for which you want to write a documentation

# First download the setup script into a temporary folder

wget {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \

   -O /tmp/setup_mkdocs.sh

# Then read the content of the script with your favorite editor

vim /tmp/setup_mkdocs.sh

# If you are confident with what the script does, make it executable and run it

chmod +x /tmp/setup_mkdocs.sh

# Note the URL of the repo specified with option `-r`

# NOTE THE USAGE OF THE `-u` OPTION

/tmp/setup_mkdocs.sh -u -r https://gitdomain.tld/namespace/mkdocs_template.git

```



Or if you already read the content of the script `setup.sh` at the root of this

repo, previous commands can be done in online:



```bash

# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION

# You can get the content of the script setup.sh via curl and pipe it into bash

# NOTE THE USAGE OF THE `-u` OPTION

curl -sfL \

  {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \

  | bash -s -- \

    -u -r https://gitdomain.tld/namespace/mkdocs_template.git

```

docs/references/preview.md

+36 −39
Original line number Original line Diff line number Diff line
@@ -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

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

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`

This will be done by creating symlinks from `templates` and `user_config`

folders into `preview` folder.

folders into `preview` folder.





Available options are:

Available options are:





  `-c,--clean`      : Remove every existing symlinks before rendering the

  * `-c,--clean`      : Remove every existing symlinks before rendering the

                        preview.

                        preview.





  `-r,--very-clean` : Remove every existing symlinks without rendering the

  * `-r,--very-clean` : Remove every existing symlinks without rendering the

                        preview.

                        preview.





  `-h,--help`       : Print this help.

  * `-h,--help`       : Print this help.













## main()

## main()





 **Setup folder to be able to use directory environment mechanism**

 **Setup preview folder to be able to see the rendering of the documentation template.**





 Check if git is installed. Then check that folder is not already using

 Build the list of the file that will be installed if using the mkdocs

 mkdocs documentation.

 documentation template, make a symlinks of all these files into `preview`

 

 folder and, depending on the options provided, render the documentation

 If directory already set to use directory environment, then check if user

 preview.

 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.





 **Globals**

 **Globals**
@@ -54,9 +49,9 @@ Available options are: 




 | Arguments | Description |

 | Arguments | Description |

 | :-------- | :---------- |

 | :-------- | :---------- |

 | `-u,--upgrade` | -u,--upgrade |

 | `-c,--clean`      |  Remove every existing symlinks before rendering the preview. |

 | `-r,--repo-url REPO_URL` | -r,--repo-url REPO_URL |

 | `-r,--very-clean` |  Remove every existing symlinks without rendering the preview. |

 | `-s,--subrepo` | -s,--subrepo |

 | `-h,--help`       |  Print this help. |





 **Output**

 **Output**
@@ -64,12 +59,12 @@ Available options are: 




 **Returns**

 **Returns**





 - 0 if directory is correctly configure to start writing documentation

 - 0, if rendering of the preview documentation went right.

 - 1 if something when wrong during the setup of documentation

 - 1, if rendering of the preview documentation went wrong.





### manpage()

### 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

> Simply extract the docstring from the header of the script, format it with

> some output enhancement (such as bold) and print it to stdout.

> some output enhancement (such as bold) and print it to stdout.
@@ -86,7 +81,7 @@ Available options are: 




### mkdocs_log()

### 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

> Echo colored log depending on user provided message severity. Message

> severity are associated to following color output:

> severity are associated to following color output:
@@ -128,18 +123,19 @@ Available options are: 
>

>

> | Arguments | Description |

> | 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()

### 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

> 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

> replace the file to be installed from `templates` by the one in

> `user_config`. Finally, add remaining `user_config` files not 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**

> **Globals**

>

>
@@ -151,6 +147,7 @@ Available options are: 




> **Recursively clean the preview folder by removing all symlinks**

> **Recursively clean the preview folder by removing all symlinks**

>

>

> Simply remove recursively all symlinks from folder `preview`.

>

>

> **Globals**

> **Globals**

>

>
@@ -165,11 +162,11 @@ Available options are: 




### setup_mkdocs()

### setup_mkdocs()





> **Recursively install base folder and script to write mkdocs documentation.**

> **Recursively install base folder and script to render a preview of the documentation template.**

>

>

> Build the list of files and folders, recursively copy all files to

> Build the list of files and folders, recursively create a symlink of all

> their right location from the temporary clone repo to the folder which

> files to their right location from the temporary clone repo to the folder

> will host the mkdocs documentation.

> `preview`.

>

>

> **Globals**

> **Globals**

>

>

docs/usage/configure.md

0 → 100644
+363 −0
Original line number Original line Diff line number Diff line 
# Configuration of the documentation



Once you have installed files using the script `setup.sh`, and before starting

to render your documentation you will need some configuration to do:



## Base mkdocs configuration



Normally, most configuration of `mkdocs` is done in `mkdocs.yml` file, but to be

able to use a templated `mkdocs.yml`, most of the configuration is handled

differently.



Now, it is the file `templates/docs/_data/plugins.py` which will handle the

configuration. This file is automatically called with the

[`mkdocs-macros-plugins`][mkdocs_macros_plugins]. So, if you want to overload

mkdocs configuration value, this is done through the file

`docs/_data/vars.yaml`. An example of such content is provided in

`docs/_data/template/vars.tpl.yaml`.



```bash

# Assuming you are at the root of the folder where you installed the documentation

cp docs/_data/template/vars.tpl.yaml docs/_data/vars.yaml

# Now edit the content of the copied file with your favorite editor

vim docs/_data/vars.yaml

```



The file is heavily commented allowing you to know what you are updating. Note

that this part is optional, as most of the `mkdocs.yml` configuration is

automatically set based on the git repo information (git remote **origin**) and

[repo variables](#repo-variables).



[mkdocs_macros_plugins]: https://mkdocs-macros-plugin.readthedocs.io/en/latest/



## Repo variables



!!! important "Ensure a git remote **origin** exists"



    Before continuing, your documentation **MUST** be a git repository with a

    remote **origin**. Indeed, the script `docs/_data/plugins.py` will get

    remote information to have the `repo_slug` to know which file in

    `docs/_data/` hold the repository information.



So assuming that your remote **origin** is

`https://mygit.tld/namespace/my_repo_slug.git` (this work also for ssh remote).

You will need to copy the template provided in `docs/_data/template/repo.tpl.yaml`

in `docs/_data/my_repo_slug` and then update its content:



```bash

# Assuming you are at the root of the repo holding the documentation

cp docs/_data/template/repo.tpl.yaml docs/_data/my_repo_slug.yaml

# Then edit the content of the file with your favorite editor

vim docs/_data/my_repo_slug.yaml

```



You will need to update some keys in the repo file which will be used to

automatically set `mkdocs.yml` configuration if not set in

`docs/_data/vars.yaml`.



For instance key `my_repo_slug['name']` will be used to dynamically set

`site_name` key of the `mkdocs.yml`.



Below is an example of such file:



```yaml

# 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`.

my_repo_slug:



  # An explicit name for the repo that will be shown on the documentation

  # page.

  name: "The Best Repo Name in the World"



  # (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/my_repo_slug.git"



  # 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/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: >-

    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

  # 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"

```



## Subrepo Variables



If you are working on a big project, with multiple subrepo you might have or

want to split the documentation such as each project hold its own but render all

of them from a master repository.



An example could be an [ansible collection][ansible_collection] which can be

composed of a master repository holding specific files and folders holdings

things like roles, etc. In this case, you might want to keep roles in other git

repository (like git submodules) and each of the role holds its own

documentation. But you want the final rendered documentation to include these

repos.



This can be done via a file describing such subrepo, i.e. the file

`docs/_data/subrepo.yaml`. To do so, copy the template provided in

`docs/_data/template/subrepo.tpl.yml`.



```bash

# Assuming you are at the root of the folder where you installed the documentation

cp docs/_data/template/subrepo.tpl.yaml docs/_data/subrepo.yaml

# Edit the content of the file with your favorite editor

vim docs/_data/subrepo.yaml

```



Below is an example of file `docs/_data/subrepo.yml` for an ansible collection

which roles are in folder `roles` at the root of the repo and such that roles

documentation are include in the final documentation.



```yaml

subrepo:

  # Folder where there are subrepo

  roles:

    # Nav entry in mkdocs.yml from where the roles documentations will be

    # include. If the entry does not exists, it will be automatically added at

    # the end of the `nav`

    nav_entry: "Roles"

      # Specify that the role will be include to the final documentation

      internal:

        # Provide a list of repo information

        - name: role_name_1

          nav_entry: My Role 1

          # You can provided both https or ssh url, but https is prefered for CI

          # to better work

          git_url: https://gitdomain.tld/namespace/subnamespace/my_role_name_1

        - name: role_name_2

          nav_entry: My Role 2

          # You can provided both https or ssh url, but https is prefered for CI

          # to better work

          git_url: https://gitdomain.tld/namespace/subnamespace/my_role_name_2

```



If you want to add link to external documentation, i.e. a link to the home page

will be included in the `nav` of the main repo but their own `nav` will not be

included, this can also be done with the file `docs/_data/subrepo.yaml`.



An example could be a main repo simply providing entry point to other repos,

such as repo holding base content of

[docs.romaindeville.fr][docs.romaindeville.fr]. Below is an example of the

content of such `subrepo.yaml` file:





```yaml

subrepo:

  # Folder where there are subrepo

  programs:

    # Nav entry in mkdocs.yml from where the roles documentations will be

    # include. If the entry does not exists, it will be automatically added at

    # the end of the `nav`

    nav_entry: "My Programs"

      # Specify repos which documentation will be external

      external:

        # Provide a list of repo information

        - name: my_first_repo

          nav_entry: Example of First External repo

          # You can provided both https or ssh url, but https is prefered for CI

          # to better work

          git_url: https://gitdomain.tld/namespace/subnamespace/my_first_repo.git

          # Link to the external documentation, can be relative to the root of

          #the documentation of a full https link.

          online_url: /relative/to/root/documentation/

        - name: my_second_repo

          nav_entry: Example of Second External repo

          # You can provided both https or ssh url, but https is prefered for CI

          # to better work

          git_url: https://gitdomain.tld/namespace/subnamespace/my_second_repo.git

          # Link to the external documentation, can be relative to the root of

          #the documentation of a full https link.

          online_url: https://domain.tld/full/external/link/

```



Of course, both `internal` and `external` can be used as shown below (click to

reveal).



??? Example



    ```yaml

    subrepo:

      # Folder where there are subrepo

      roles:

        # Nav entry in mkdocs.yml from where the roles documentations will be

        # include. If the entry does not exists, it will be automatically added at

        # the end of the `nav`

        nav_entry: "Roles"

          # Specify that the role will be include to the final documentation

          internal:

            # Provide a list of repo information

            - name: role_name_1

              nav_entry: My Role 1

              # You can provided both https or ssh url, but https is prefered for CI

              # to better work

              git_url: https://gitdomain.tld/namespace/subnamespace/my_role_name_1

            - name: role_name_2

              nav_entry: My Role 2

              # You can provided both https or ssh url, but https is prefered for CI

              # to better work

          # Specify repos which documentation will be external

          external:

            # Provide a list of repo information

            - name: my_first_role

              nav_entry: Example of First External Role

              # You can provided both https or ssh url, but https is prefered for CI

              # to better work

              git_url: https://gitdomain.tld/namespace/subnamespace/my_first_role.git

              # Link to the external documentation, can be relative to the root of

              #the documentation of a full https link.

              online_url: /relative/to/root/documentation/

      programs:

        nav_entry: "My Programs"

          # Specify repos which documentation will be external

          external:

            # Provide a list of repo information

            - name: my_first_repo

              nav_entry: Example of First External repo

              # You can provided both https or ssh url, but https is prefered for CI

              # to better work

              git_url: https://gitdomain.tld/namespace/subnamespace/my_first_repo.git

              # Link to the external documentation, can be relative to the root of

              #the documentation of a full https link.

              online_url: /relative/to/root/documentation/

            - name: my_second_repo

              nav_entry: Example of Second External repo

              # You can provided both https or ssh url, but https is prefered for CI

              # to better work

              git_url: https://gitdomain.tld/namespace/subnamespace/my_second_repo.git

              # Link to the external documentation, can be relative to the root of

              #the documentation of a full https link.

              online_url: https://domain.tld/full/external/link/

    ```



Thus, when rendering the documentation, the script `docs/_data/plugins.py` will

check if folders `roles/{role_name_1,role_name_2}` exists. If they exists and

are git repo, script will pull them to get the last version. If they do not

exists, the will be cloned.



Finally, the script `docs/_data/plugins.py` will update the `nav` of the

documentation with these repos and will load file `docs/_data/repo.yaml`

of each repo allowing to access to the repo informations.





## Extra variables



All of the above files will create variables which can be used in your

documentation using [mkdocs-macros-plugin][mkdocs-macros-plugin]. If you want to

add extra variables which are not in `vars.yaml`, nor `repo.yaml`, neither in

`subrepo.yaml`, you can do it by settings them in a file

`docs/_data/extra.yaml`. Indeed, previously mentionned filed will be checked

against a schema (provided in `docs/_data/{repo,subrepo,vars}.schema.yaml`),

thus do not allow extra variables to ensure stability of script

`docs/_data/plugins.py` while file `docs/_data/extra.yaml` is loaded as it is

without schema control.



[mkdocs-macros-plugin]: https://mkdocs-macros-plugin.readthedocs.io/en/latest/



## Variable usage



Finally, as describe above some variables are used for the configuration to

render documentation. But they can also be use in your markdown documentation

files using jinja template. For instance, below is a basic content of a markdown

file showing the name of the main repo, its description and a list of roles and

programs with their description.



=== "Markdown"



    ```jinja

    {% raw %}

    <!-- Print the name of the repo -->

    # {{ my_repo_slug.name }}



    <!-- Print the desc of the repo -->

    {{ my_repo_slug.desc }}



    <!-- Print a section and a table with repo information from subrepo -->

    {%- for i_key in subrepo %}

    <!-- Print the title of the section from `nav_entry` in subrepo -->

    # {{ subrepo[i_key].nav_entry }}



    <!-- Start the table with repo information -->

    | Name | Description |

    | ---- | ----------- |

    {%-   for i_repo_type in subrepo[i_key] %}

    {%-     if i_repo_type in ("external","internal") %}

    {%-       for i_repo in subrepo[i_key][i_repo_type] %}

    {# Get the content of the dictionary #}

    {%-     set curr_repo = subs(i_repo.name) %}

    | {{ curr_repo.name }} | {{ curr_repo.desc }}

    {%-       endfor %}

    {%-     endif %}

    {%-   endfor %}

    {%- endfor %}

    {% endraw %}

    ```

=== "Rendered HTML"



    # {{ example.my_repo_slug.name }}



    {{ example.my_repo_slug.desc }}



    {%- for i_key in example.subrepo %}



    ## {{ example.subrepo[i_key].nav_entry }}



    | Name | Description |

    | ---- | ----------- |

    {%-   for i_repo_type in example.subrepo[i_key] %}

    {%-     if i_repo_type in ("external","internal") %}

    {%-       for i_repo in example.subrepo[i_key][i_repo_type] %}

    {#- Get the content of the dictionary #}

    {%-         set curr_repo = subs(i_repo.name) %}

    | {{ curr_repo.name }} | {{ curr_repo.desc }} |

    {%-       endfor %}

    {%-     endif %}

    {%-   endfor %}

    {%- endfor %}





You are now ready to write your documentation. Juste remember **to not update**

content between markdown tags.



Moreover, later the main template may get upgraded (like adding new feature or

providing new template content), to automatically apply this upgrade to your

documentation see [Upgrade][upgrade].



And finally, you may want to provide your own template, with custom CSS for

instance, or pre-fill index documentation page, to do so, set [Setup Your Own

Template][setup_your_own_template]



[ansible_collection]: https://docs.ansible.com/ansible/latest/dev_guide/developing_collections.html#collection-structure

[docs.romaindeville.fr]: {{ site_base_url }}

[upgrade]: upgrade.md

[setup_your_own_template]: ../personal_template/index.md

docs/usage/index.md

0 → 100644
+11 −0
Original line number Original line Diff line number Diff line 
# Usage of this repo



In this section of the documentation, you will see how to :



  - [Setup a MKDocs Template][setup]

  - [Configure Installed Template][configure]

  - [Upgrade Template to latest version][upgrade]



[setup]: setup.md

[configure]: configure.md

[upgrade]: upgrade.md

docs/usage/setup.md

0 → 100644
+147 −0
Original line number Original line Diff line number Diff line 
{% set curr_repo=subs("mkdocs_template") %}

# Setup a template



The installation of a mkdocs documentation from a template is done using the

script `setup.sh` at the root of the repo.



{% include "docs/usage/setup.sh.md" %}



## Installation of the template



Assuming you want to use the **really** basic template provided at [{{

git_platform.name }} - {{ curr_repo.git_name_with_namespace }}]({{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}). In a repo in which you

want to create a documentation, type the following commands:



```bash

# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION

# First download the setup script into a temporary folder

wget {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \

   -O /tmp/setup_mkdocs.sh

# Then read the content of the script with your favorite editor

vim /tmp/setup_mkdocs.sh

# If you are confident with what the script does, make it executable and run it

chmod +x /tmp/setup_mkdocs.sh

/tmp/setup_mkdocs.sh -r {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}

```



Or if you already read the content of the script `setup.sh` at the root of this

repo, previous commands can be done in one line:



```bash

# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION

# You can get the content of the script setup.sh via curl and pipe it into bash

curl -sfL \

  {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \

  | bash -s -- \

    -r {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}

```



This will automatically copy the content of folder `templates` of the Mkdocs

Template project in the folder where you are located.



Note that some copied files will have comment tag automatically added if they

are not present. For instance, following example content:



```markdown

# Title



Sample content of a page

```



Will be copied with the following tags:



```md

<!-- BEGIN MKDOCS TEMPLATE -->

<!-- WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! -->

<!-- Modified content will be overwritten when updating -->

# Title



Sample content of a page



<!-- END MKDOCS TEMPLATE -->

```



These tags serve as delimiter of the template content, without them, any

modification you may have done on copied files will be overwritten when you will

upgrade to a latest template version.



So this allow you to add content before and after these tags, content you will

add before and after will not be modified when upgrading while content between

tags might be updated if latest version contain update.



In other words, you might do the following:



```md

# Previous title



Content added by the user, which will not be updated in case of upgrade of the

template.



<!-- BEGIN MKDOCS TEMPLATE -->

<!-- WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! -->

<!-- Modified content will be overwritten when updating -->

# Title



Sample content of a page



<!-- END MKDOCS TEMPLATE -->



# Next title



Content added by the user, which will not be updated in case of upgrade of the

template.

```



The tag comment depends on the extension of the file copied:



  - `*.md`, `*.html` or `*LICENSE`, will have following tags:

    ```html

    <!-- BEGIN MKDOCS TEMPLATE -->

    <!-- WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! -->

    <!-- Modified content will be overwritten when updating -->



    […]



    <!-- END MKDOCS TEMPLATE -->

    ```



  - `*.css`, `*.js`, will have following tags:

    ```css

    /* BEGIN MKDOCS TEMPLATE */

    /* WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! */

    /* Modified content will be overwritten when updating */



    […]



    /* END MKDOCS TEMPLATE */

    ```



  - `*.yaml`, `*.yml`, `*.gitignore`, `*.toml`, `*.in`, `*.txt`, will have

    ```yaml

    ### BEGIN MKDOCS TEMPLATE ##

    ### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! ###

    ### Modified content will be overwritten when updating ###

    ###



    […]



    ### END MKDOCS TEMPLATE ###

    ```



  - Files with other extension will not have comment tags, this is mainly for

    source code file or svg images for instance.





Moreover, if there is already mkdocs tags in the file, the complete file will be

copied during setup but only content between tags will be overwritten when

upgrading.



For instance, the file `mkdocs.yml` has most of its content between tags, only

the end is not between tags. So when installing the template for the first time,

all of the file will be installed while when upgrading only content between tag

will be overwritten.



Once you have install the mkdocs template files using the script `setup.sh` you

now have some [configuration][configuration] to do.



[configuration]: configure.md

docs/usage/setup.sh.md

0 → 100644
+33 −0
Original line number Original line Diff line number Diff line 
## Synopsis of `setup.sh`



`./setup.sh [-u|--upgrade] [-s|--subrepo] [-h|--help] -r|--repo-url REPO_URL`



## Description



This script will install/upgrade set of scripts and files to create and

manage documentation rendered using mkdocs.



If directory is already using mkdocs and user does not provide

`-u|--upgrade` options, an error will be shown and nothing will be done.



If user does not provide REPO_URL from which download the template, i.e.

using option `-r|--repo-url REPO_URL`, then an error will be prompt and

the script will exit.



## Options



Available options are:



  * `-u,--upgrade`  : Upgrade the current mkdocs documentation to the latest

                      template version.



  * `-s,--subrepo`  : Specify the current repo is a subrepo that will be

                      merge into another main project using mkdocs-monorepo

                      plugin.



  * `-r,--repo-url` : URL of the repo from which the template will be

                      downloaded.



  * `-h,--help`     : Print the help.

docs/usage/upgrade.md

0 → 100644
+46 −0
Original line number Original line Diff line number Diff line 
{% set curr_repo=subs("mkdocs_template") %}

# Upgrade to latest template



If the source template get new features, like improving `plugins.py` script,

you might want to get them. To do so is as easy as installing the documentation.

This is done using the script `setup.sh` with the option `-u`. Below is a recall

of the usage of the script



{% include "docs/usage/setup.sh.md" %}



## How to upgrade



This is done by using the option `-u` of the script `setup.sh`. Using this

option, the script will compare last version with old version of each files. If

they have changed, backup the old version, to avoid losing content in case of

error and then upgrade the files to the latest version.



```bash

# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION

# First download the setup script into a temporary folder

wget {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \

   -O /tmp/setup_mkdocs.sh

# Then read the content of the script with your favorite editor

vim /tmp/setup_mkdocs.sh

# If you are confident with what the script does, make it executable and run it

chmod +x /tmp/setup_mkdocs.sh

# NOTE THE USAGE OF THE `-u` OPTION

/tmp/setup_mkdocs.sh -u -r {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}

```



Or if you already read the content of the script `setup.sh` at the root of this

repo, previous commands can be done in online:



```bash

# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION

# You can get the content of the script setup.sh via curl and pipe it into bash

# NOTE THE USAGE OF THE `-u` OPTION

curl -sfL \

  {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \

  | bash -s -- \

    -u -r {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}

```



This will automatically upgrade the content of your documentation from the

template to its latest version.

mkdocs.yml

+161 −52
Original line number Original line Diff line number Diff line
@@ -28,7 +28,7 @@ theme: 
  # https://squidfunk.github.io/mkdocs-material/

  # https://squidfunk.github.io/mkdocs-material/

  name: material

  name: material

  # Overriding parent theme configuration

  # Overriding parent theme configuration

  #custom_dir: docs/theme

  custom_dir: docs/theme

  # Determines whether the search plugin expects the theme to provide a

  # Determines whether the search plugin expects the theme to provide a

  # dedicated search page via a template located at search/search.html.

  # dedicated search page via a template located at search/search.html.

  include_search_page: false

  include_search_page: false
@@ -44,37 +44,80 @@ theme: 
    - navigation.tabs

    - navigation.tabs

    - navigation.instant

    - navigation.instant

    - navigation.top

    - navigation.top

  # Setting colors palette

  # Setting colors palette (these are defined in docs/theme/css/{colors,theme}.css)

  palette:

  palette:

    # Light mode

    # Light mode

    - media: "(prefers-color-scheme: light)"

    - media: "(prefers-color-scheme: light)"

      scheme: default

      scheme: rdeville-light

      primary: deep-purple

      primary: rdeville-green-light

      accent: yellow

      accent: rdeville-orange-light

      toggle:

      toggle:

        icon: material/weather-sunny

        icon: material/weather-night

        name: Switch to dark mode

        name: Switch to dark mode

    # Dark mode

    # Dark mode

    - media: "(prefers-color-scheme: dark)"

    - media: "(prefers-color-scheme: dark)"

      scheme: slate

      scheme: rdeville-dark

      primary: deep-purple

      primary: rdeville-green-dark

      accent: yellow

      accent: rdeville-orange-dark

      toggle:

      toggle:

        icon: material/weather-night

        icon: material/weather-sunny

        name: Switch to light mode

        name: Switch to light mode

  # Font configuration for the website

  # Font configuration for the website (FurCode are provided in

  # docs/theme/fonts)

  font: false

  font: false

  #  text:

  #  text: FuraCode Nerd Font

  #  code:

  #  code: FuraCode Nerd Font

  # Path to logo and icons to use for the website

  # Path to logo and icons to use for the website

  #logo:    # Automatically set by mkdocs_macros_plugin (see docs/_data/plugins.py)

  #logo:    # Automatically set by mkdocs_macros_plugin (see docs/_data/plugins.py)

  #icon:

  #icon:

  #  repo:  # Automatically set by mkdocs_macros_plugin (see docs/_data/plugins.py)

  #  repo:  # Automatically set by mkdocs_macros_plugin (see docs/_data/plugins.py)

  #favicon: # Automatically set by mkdocs_macros_plugin (see docs/_data/plugins.py)

  #favicon: # Automatically set by mkdocs_macros_plugin (see docs/_data/plugins.py)





# External CSS

# ---------------------------------------------------------------------------

extra_css:

  # Define css for lightgallery

  # From: https://github.com/g-provost/lightgallery-markdown

  - theme/css/lightgallery.css

  # Define personal extra css

  - theme/css/extra.css

  # Define colors (all materials colors RGB code)

  - theme/css/colors.css

  # Define fonts

  - theme/css/fonts.css

  # Define themes

  - theme/css/theme.css

  # Define css of base markdown extension and pymdown extension

  - theme/css/python_markdown_extension.css



# External JS

# ---------------------------------------------------------------------------

extra_javascript:

  # Define javascript for lightgallery

  # From: https://github.com/g-provost/lightgallery-markdown

  - theme/js/lightgallery.js

  - theme/js/lg-video.js

  # Define javascript for arithmatex (auto downloaded with tools/upgrade_external_dependencies)

  # From: https://squidfunk.github.io/mkdocs-material/reference/mathjax/#arithmatex

  - theme/js/polyfill.js

  - theme/js/es5/tex-chtml.js

  # Define javascript to allow table sorting

  # From: https://squidfunk.github.io/mkdocs-material/reference/data-tables/#sortable-tables

  - theme/js/tablesort.min.js

  # Define javascript for mermaid

  # From: https://github.com/fralau/mkdocs-mermaid2-plugin#explicit-declaration-of-the-mermaid-library

  - theme/js/mermaid.js

  # Define javascript for custom pymdown mermaid loader

  # From: https://facelessuser.github.io/pymdown-extensions/extras/mermaid/#custom-loader

  - theme/js/mermaid-loader.js

  # Define personal custom javascript

  - theme/js/extra.js



# Extensions

# Extensions

# ---------------------------------------------------------------------------

# ---------------------------------------------------------------------------

markdown_extensions:

markdown_extensions:

  # Allow to include markdown files

  # https://github.com/sethen/markdown-include

  - markdown_include.include:

  - markdown_include.include:

      base_path: ./

      base_path: ./

  # Python Markdown Extensions

  # Python Markdown Extensions
@@ -94,53 +137,97 @@ markdown_extensions: 
  - markdown.extensions.md_in_html:

  - markdown.extensions.md_in_html:

  # Pymdown Extensions

  # Pymdown Extensions

  # https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/

  # https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/

  - pymdownx.extra:

  - pymdownx.arithmatex:

      generic: true

  - pymdownx.betterem:

  - pymdownx.betterem:

  - pymdownx.tabbed:

  - pymdownx.details:

  - pymdownx.superfences:

  - pymdownx.caret:

      preserve_tabs: true

  - pymdownx.escapeall:

      # Make exceptions to highlighting code of following classes:

      hardbreak: True

      custom_fences:

      nbsp: True

  - pymdownx.critic:

  - pymdownx.emoji:

      emoji_index: !!python/name:pymdownx.emoji.twemoji

      emoji_generator: !!python/name:pymdownx.emoji.to_svg

      options:

        image_path: /assets/twemoji/svg/

        custom_icons:

          - .icons

  - pymdownx.inlinehilite:

      custom_inline:

        - name: math

        - name: math

          class: arithmatex

          class: arithmatex

          format: !!python/name:pymdownx.arithmatex.fence_mathjax_format

          format: !!python/name:pymdownx.arithmatex.inline_generic_format

  - pymdownx.highlight:

  - pymdownx.highlight:

      linenums: true

      linenums_special: 2

      linenums_style: pymdownx-inline

      guess_lang: false

      extend_pygments_lang:

      extend_pygments_lang:

        - name: php-inline

          lang: php

          options:

            startinline: true

        - name: pycon3

        - name: pycon3

          lang: pycon

          lang: pycon

          options:

          options:

            python3: true

            python3: true

      linenums_style: pymdownx-inline

  - pymdownx.keys:

  - pymdownx.inlinehilite:

      separator: "\uff0b"

      custom_inline:

  - pymdownx.mark:

  - pymdownx.magiclink:

      repo_url_shortener: true

  - pymdownx.progressbar:

  - pymdownx.pathconverter:

  - pymdownx.smartsymbols:

  - pymdownx.snippets:

  - pymdownx.striphtml:

  - pymdownx.superfences:

      preserve_tabs: true

      # Make exceptions to highlighting code of following classes:

      custom_fences:

        - name: math

        - name: math

          class: arithmatex

          class: arithmatex

          format: !!python/name:pymdownx.arithmatex.inline_mathjax_format

          format: !!python/name:pymdownx.arithmatex.fence_generic_format

  - pymdownx.tilde:

        - name: mermaid

  - pymdownx.caret:

          class: mermaid

  - pymdownx.critic:

          format: !!python/name:pymdownx.superfences.fence_code_format

  - pymdownx.smartsymbols:

  - pymdownx.tabbed:

  - pymdownx.emoji:

      emoji_index: !!python/name:materialx.emoji.twemoji

      emoji_generator: !!python/name:materialx.emoji.to_svg

      options:

        custom_icons:

          - .icons

  - pymdownx.escapeall:

      hardbreak: True

      nbsp: True

  - pymdownx.tasklist:

  - pymdownx.tasklist:

      custom_checkbox: true

      custom_checkbox: true

  - pymdownx.progressbar:

  - pymdownx.tilde:

  - pymdownx.arithmatex:

  # Locally installed in docs/theme/plugins/ from original repo

  - pymdownx.mark:

  # https://github.com/g-provost/lightgallery-markdown

  - pymdownx.striphtml:

  - lightgallery:

  - pymdownx.keys:



      separator: "\uff0b"

# Extra Data Information & Customization

  - pymdownx.details:

# ---------------------------------------------------------------------------

# Dictionary storing social icon that will be shown on the bottom right.

extra:

  social:

    - icon: fontawesome/solid/globe

      link: https://romaindeville.fr

      name: R. Deville Wesite

    - icon: fontawesome/solid/paper-plane

      link: mailto:contact@romaindeville.fr

      name: "Send mail to @rdeville"

    - icon: fontawesome/solid/book-reader

      link: https://docs.romaindeville.fr

      name: All Projects Home Documentation

    - icon: fontawesome/brands/linkedin

      link: https://www.linkedin.com/in/romaindeville

      name: "@rdeville on LinkedIn"

    - icon: fontawesome/brands/docker

      link: https://hub.docker.com/u/rdeville

      name: "@rdeville on Docker Hub"

    - icon: fontawesome/brands/git-alt

      link: https://framagit.org/rdeville.public/

      name: "@rdeville on Framagit"

    - icon: fontawesome/brands/gitlab

      link: https://gitlab.com/rdeville.public/

      name: "@rdeville on Gitlab"

    - icon: fontawesome/brands/github

      link: https://github.com/rdeville-public/

      name: "@rdeville on Github"

  version:

    provider: mike





# Plugins

# Plugins

# ---------------------------------------------------------------------------

# ---------------------------------------------------------------------------
@@ -173,6 +260,12 @@ plugins: 
    # This plugin enables you to build multiple sets of documentation in a

    # This plugin enables you to build multiple sets of documentation in a

    # single Mkdocs.

    # single Mkdocs.

  - monorepo:

  - monorepo:

  # A Mermaid graphs plugin for mkdocs

  # https://github.com/fralau/mkdocs-mermaid2-plugin#declaring-the-superfences-extension

  - mermaid2:

      arguments:

        theme: |

          ^(localStorage.getItem('theme') === 'rdeville-dark') ? 'dark'  : 'light'

    # https://pawamoy.github.io/mkdocstrings/

    # https://pawamoy.github.io/mkdocstrings/

    # Automatic documentation from sources, for MkDocs.

    # Automatic documentation from sources, for MkDocs.

  - mkdocstrings:

  - mkdocstrings:
@@ -182,21 +275,37 @@ plugins: 
          rendering:

          rendering:

            show_source: true

            show_source: true

            show_if_no_docstring: true

            show_if_no_docstring: true

            show_root_heading: false

            show_root_toc_entry: false

            show_root_full_path: true

            show_object_full_path: true

            show_root_members_full_path: true

            show_category_heading: true

            show_signature_annotations: false

            group_by_category: true

            heading_level: 2

          setup_commands:

          setup_commands:

            - import sys

            - import sys

            # Others command such as sys.path.append("path") are

            # Others command such as sys.path.append("path") are

            # Automatically added using mkdocs_macros_plugin

            # Automatically added using mkdocs_macros_plugin

            # (see docs/_data/plugins.py)

            # (see docs/_data/plugins.py)

# DO NOT FORGET TO ADD/UPDATE THE \`nav\` AND \`extra\` KEYS BELOW.

# DO NOT FORGET TO ADD/UPDATE THE \`nav\` KEY BELOW.

### END MKDOCS TEMPLATE ###

### END MKDOCS TEMPLATE ###





extra:

  version:

    provider: mike

# Navigation Pane

# Navigation Pane

# ---------------------------------------------------------------------------

# ---------------------------------------------------------------------------

nav:

nav:

  - Home: index.md

  - Home: index.md

  - Use Template:

    - usage/index.md

    - Setup Template: usage/setup.md

    - Configure Installed Template: usage/configure.md

    - Upgrade Template: usage/upgrade.md

  - Setup Your Own Template:

    - personal_template/index.md

    - Create Your Template: personal_template/create.md

    - Use Your Template: personal_template/usage.md

    - Example: personal_template/example.md

  - Code References:

  - Code References:

    - setup.sh: references/setup.md

    - setup.sh: references/setup.md

    - preview.sh: references/preview.md

    - preview.sh: references/preview.md

preview/docs/_data/vars.yaml

deleted100644 → 0
+0 −97
Original line number Original line Diff line number Diff line 
### BEGIN MKDOCS TEMPLATE ###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### Modified content will be overwritten when updating.###



# 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/"



### END MKDOCS TEMPLATE ###

pyproject.toml

+26 −44
Original line number Original line Diff line number Diff line 
# No need for [build-system] as this pyproject.toml per PEP-518 as this file

# No need for [build-system] as this pyproject.toml per PEP-518 as this file

# serve to a centralized configuration file for development tools such as

# serve to a centralized configuration file for development tools such as

# black, flake8/flakehell, pylint, pycodestyle, etc.

# black, flake8/flake9, pylint, pycodestyle, etc.

[build-system]

[build-system]

requires = [

requires = [

  "setuptools",

  "setuptools",
@@ -45,9 +45,9 @@ commands = 
        -not -path "./tmp/*" \

        -not -path "./tmp/*" \

        -not -path "./site**/*"  \\) )'

        -not -path "./site**/*"  \\) )'

  # Lint python files using flake8

  # Lint python files using flake8

  flakehell lint

  flake8

  # Ensure docstring convention (google is mkdocs rendering documentation)

  # Ensure docstring convention (google is mkdocs rendering documentation)

  pydocstyle --count --match-dir="(?![^\\.(docs)]).*" --convention=google

  pydocstyle --count --convention=google --match-dir='[^(\\.|preview)].*'





[testenv:format_shell]

[testenv:format_shell]

# Allow external commands

# Allow external commands
@@ -69,6 +69,7 @@ commands = 
        -not -path "./python_venv/*" \\) ) '

        -not -path "./python_venv/*" \\) ) '

  bash -c 'DIRENV_ROOT="$(pwd)" ./tools/generate_source_docs.sh --dry-run'

  bash -c 'DIRENV_ROOT="$(pwd)" ./tools/generate_source_docs.sh --dry-run'







[testenv:build_doc]

[testenv:build_doc]

# Allow external commands

# Allow external commands

allowlist_externals=

allowlist_externals=
@@ -91,6 +92,8 @@ commands = 
"""

"""













### BEGIN MKDOCS TEMPLATE ###

### BEGIN MKDOCS TEMPLATE ###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! ###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! ###

### Modified content will be overwritten when updating. ###

### Modified content will be overwritten when updating. ###
@@ -1086,9 +1089,9 @@ overgeneral-exceptions=["BaseException","Exception"] 








# -----------------------------------------------------------------------------

# -----------------------------------------------------------------------------

# Flake8 wrapper to make it nice, legacy-friendly, configurable.

# Flake8/flake9

# https://flakehell.readthedocs.io/config.html

# https://flake8.pycqa.org/en/latest/user/configuration.html

[tool.flakehell]

[tool.flake8]

  # Optionally inherit from remote config (or local if you want)

  # Optionally inherit from remote config (or local if you want)

#base=https://url.git.com/pyproject.toml

#base=https://url.git.com/pyproject.toml
@@ -1098,22 +1101,10 @@ overgeneral-exceptions=["BaseException","Exception"] 
count = true

count = true





  # Provide a comma-separated list of glob patterns to exclude from checks.

  # Provide a comma-separated list of glob patterns to exclude from checks.

exclude=[

exclude = ".git,__pycache__,.eggs,.env,.venv,.direnv,.tox,.sha1,build,dist,docs,site"

  ".git",

  "__pycache__",

  ".eggs",

  ".venv",

  ".direnv",

  ".tox",

  ".sha1",

  "build",

  "dist",

  "docs",

  "site"

]





  # Provide a comma-separate list of glob patterns to include for checks.

  # Provide a comma-separate list of glob patterns to include for checks.

filename=[ "*.py" ]

filename = "*.py"





  # Select the formatter used to display errors to the user.

  # Select the formatter used to display errors to the user.

  # This defaults to: default

  # This defaults to: default
@@ -1123,12 +1114,12 @@ filename=[ "*.py" ] 
  #  - colored

  #  - colored

  # The default formatter has a format string of:

  # The default formatter has a format string of:

  # '%(path)s:%(row)d:%(col)d: %(code)s %(text)s'

  # '%(path)s:%(row)d:%(col)d: %(code)s %(text)s'

format="grouped"

#format="colored





  # Toggle whether pycodestyle should enforce matching the indentation of the

  # Toggle whether pycodestyle should enforce matching the indentation of the

  # opening bracket’s line. When you specify this, it will prefer that you hang

  # opening bracket’s line. When you specify this, it will prefer that you hang

  # the closing bracket rather than match the indentation.

  # the closing bracket rather than match the indentation.

hang_closing=false

hang-closing = false





  # Specify a list of codes to ignore. The list is expected to be comma-separated,

  # Specify a list of codes to ignore. The list is expected to be comma-separated,

  # and does not need to specify an error code exactly. Since Flake8 3.0, this can

  # and does not need to specify an error code exactly. Since Flake8 3.0, this can
@@ -1137,8 +1128,9 @@ hang_closing=false 
  # if you want to ignore all codes that start with W23 you need only specify W23

  # if you want to ignore all codes that start with W23 you need only specify W23

  # to ignore them. This also works for W2 and W (for example).

  # to ignore them. This also works for W2 and W (for example).

  # This defaults to: E121,E123,E126,E226,E24,E704

  # This defaults to: E121,E123,E126,E226,E24,E704

  # REMARK: Not parsed by flakehell, use plugins

ignore = "E121,E123,E126,E226,E24,E704,W503,E501"

#ignore=[ "E121", "E123", "E126", "E226", "E24", "E704"]

  # W503 : line break before binary operator

  # E501 : line to long (already handled by black)





  # Set the maximum length that any line (with some exceptions) may be.

  # Set the maximum length that any line (with some exceptions) may be.

  # Exceptions include lines that are either strings or comments which are

  # Exceptions include lines that are either strings or comments which are
@@ -1149,17 +1141,17 @@ hang_closing=false 
  #   'http://...'

  #   'http://...'

  # )

  # )

  # This defaults to: 79

  # This defaults to: 79

max_line_length=80

max-line-length = 80





  # Report all errors, even if it is on the same line as a # NOQA comment. # NOQA

  # Report all errors, even if it is on the same line as a # NOQA comment. # NOQA

  # can be used to silence messages on specific lines. Sometimes, users will want

  # can be used to silence messages on specific lines. Sometimes, users will want

  # to see what errors are being silenced without editing the file. This option

  # to see what errors are being silenced without editing the file. This option

  # allows you to see all the warnings, errors, etc. reported.

  # allows you to see all the warnings, errors, etc. reported.

  # This default to : False

  # This default to : False

disable_noqa=true

disable-noqa = true





  # Print the source code generating the error/warning in question.

  # Print the source code generating the error/warning in question.

show_source=true

show-source = true





  # Count the number of occurrences of each error/warning code and print a report.

  # Count the number of occurrences of each error/warning code and print a report.

statistics = true

statistics = true
@@ -1180,9 +1172,6 @@ statistics=true 
  # by multiprocessing.cpu_count().

  # by multiprocessing.cpu_count().

jobs = "auto"

jobs = "auto"





  # Redirect all output to the specified file.

output-file=".direnv/log/flakehell.log"



  # Also print output to stdout if output-file has been configured.

  # Also print output to stdout if output-file has been configured.

tee = true

tee = true
@@ -1212,16 +1201,9 @@ tee=true 
  #  dir/subdir/file.py,

  #  dir/subdir/file.py,

  #  dir/other/file.py

  #  dir/other/file.py





[tool.flakehell.plugins]

### END MKDOCS TEMPLATE ###

  # Python code style checker

  # https://pypi.org/project/pycodestyle/

pycodestyle=["-W503"]





  # Passive checker of Python programs

  # https://pypi.org/project/pyflakes/

pyflakes=["+*"]





### END MKDOCS TEMPLATE ###









# *****************************************************************************

# *****************************************************************************

requirements.dev.in

+7 −5
Original line number Original line Diff line number Diff line 




### BEGIN MKDOCS TEMPLATE ###

### BEGIN MKDOCS TEMPLATE ###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### Modified content will be overwritten when updating.###

### Modified content will be overwritten when updating.###



# DEVELOPER REQUIREMENTS

# DEVELOPER REQUIREMENTS

# ============================================================

# ============================================================

# DESCRIPTION:

# DESCRIPTION:
@@ -25,9 +26,9 @@ isort 
# https://pypi.org/project/pytest/

# https://pypi.org/project/pytest/

pytest

pytest





# Flake8 wrapper to make it nice and configurable

# Flake8 with pyproject support

# https://pypi.org/project/flake8/

# https://pypi.org/project/flake9/

flakehell

flake9





# python code static checker

# python code static checker

# https://pypi.org/project/pylint/

# https://pypi.org/project/pylint/
@@ -44,5 +45,6 @@ shellcheck-py 
# A linter for YAML files.

# A linter for YAML files.

# https://pypi.org/project/yamllint/

# https://pypi.org/project/yamllint/

yamllint

yamllint



### END MKDOCS TEMPLATE ###

### END MKDOCS TEMPLATE ###

requirements.dev.txt

+15 −32
Original line number Original line Diff line number Diff line 
### BEGIN MKDOCS TEMPLATE ###

### BEGIN MKDOCS TEMPLATE ###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### Modified content will be overwritten when updating.###

### Modified content will be overwritten when updating.###



#

#

# This file is autogenerated by pip-compile

# This file is autogenerated by pip-compile

# To update, run:

# To update, run:
@@ -12,27 +11,21 @@ appdirs==1.4.4 
    # via

    # via

    #   black

    #   black

    #   virtualenv

    #   virtualenv

astroid==2.5.2

astroid==2.5.6

    # via pylint

    # via pylint

attrs==20.3.0

attrs==21.2.0

    # via pytest

    # via pytest

black==20.8b1

black==21.5b0

    # via -r requirements.dev.in

    # via -r requirements.dev.in

click==7.1.2

click==7.1.2

    # via black

    # via black

colorama==0.4.4

    # via flakehell

distlib==0.3.1

distlib==0.3.1

    # via virtualenv

    # via virtualenv

entrypoints==0.3

    # via flakehell

filelock==3.0.12

filelock==3.0.12

    # via

    # via

    #   tox

    #   tox

    #   virtualenv

    #   virtualenv

flake8==3.9.0

flake9==3.8.3.post2

    # via flakehell

flakehell==0.9.0

    # via -r requirements.dev.in

    # via -r requirements.dev.in

iniconfig==1.1.1

iniconfig==1.1.1

    # via pytest

    # via pytest
@@ -44,7 +37,7 @@ lazy-object-proxy==1.6.0 
    # via astroid

    # via astroid

mccabe==0.6.1

mccabe==0.6.1

    # via

    # via

    #   flake8

    #   flake9

    #   pylint

    #   pylint

mypy-extensions==0.4.3

mypy-extensions==0.4.3

    # via black

    # via black
@@ -64,27 +57,25 @@ py==1.10.0 
    # via

    # via

    #   pytest

    #   pytest

    #   tox

    #   tox

pycodestyle==2.7.0

pycodestyle==2.6.0

    # via flake8

    # via flake9

pydocstyle==6.0.0

pydocstyle==6.0.0

    # via -r requirements.dev.in

    # via -r requirements.dev.in

pyflakes==2.3.1

pyflakes==2.2.0

    # via flake8

    # via flake9

pygments==2.8.1

pylint==2.8.2

    # via flakehell

pylint==2.7.4

    # via -r requirements.dev.in

    # via -r requirements.dev.in

pyparsing==2.4.7

pyparsing==2.4.7

    # via packaging

    # via packaging

pytest==6.2.3

pytest==6.2.4

    # via -r requirements.dev.in

    # via -r requirements.dev.in

pyyaml==5.4.1

pyyaml==5.4.1

    # via yamllint

    # via yamllint

regex==2021.4.4

regex==2021.4.4

    # via black

    # via black

shellcheck-py==0.7.1.1

shellcheck-py==0.7.2.1

    # via -r requirements.dev.in

    # via -r requirements.dev.in

six==1.15.0

six==1.16.0

    # via

    # via

    #   tox

    #   tox

    #   virtualenv

    #   virtualenv
@@ -93,23 +84,15 @@ snowballstemmer==2.1.0 
toml==0.10.2

toml==0.10.2

    # via

    # via

    #   black

    #   black

    #   flakehell

    #   pylint

    #   pylint

    #   pytest

    #   pytest

    #   tox

    #   tox

tox==3.23.0

tox==3.23.1

    # via -r requirements.dev.in

    # via -r requirements.dev.in

typed-ast==1.4.2

virtualenv==20.4.6

    # via black

typing-extensions==3.7.4.3

    # via black

urllib3==1.26.4

    # via flakehell

virtualenv==20.4.3

    # via tox

    # via tox

wrapt==1.12.1

wrapt==1.12.1

    # via astroid

    # via astroid

yamllint==1.26.1

yamllint==1.26.1

    # via -r requirements.dev.in

    # via -r requirements.dev.in



### END MKDOCS TEMPLATE ###
 
### END MKDOCS TEMPLATE ###

requirements.docs.in

+12 −4
Original line number Original line Diff line number Diff line 


### BEGIN MKDOCS TEMPLATE ###

### BEGIN MKDOCS TEMPLATE ###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### Modified content will be overwritten when updating.###

### Modified content will be overwritten when updating.###



# DOCUMENTATION REQUIREMENTS

# DOCUMENTATION REQUIREMENTS

# ============================================================

# ============================================================

# DESCRIPTION:

# DESCRIPTION:
@@ -16,7 +14,7 @@ mkdocs 




# A Material Design theme for MkDocs

# A Material Design theme for MkDocs

# https://pypi.org/project/mkdocs-material/

# https://pypi.org/project/mkdocs-material/

mkdocs-material

mkdocs-material>=7.1





# Plugin for adding monorepository support in Mkdocs.

# Plugin for adding monorepository support in Mkdocs.

# https://pypi.org/project/mkdocs-monorepo-plugin/

# https://pypi.org/project/mkdocs-monorepo-plugin/
@@ -51,5 +49,15 @@ mkdocs-exclude 
# https://pypi.org/project/pykwalify/

# https://pypi.org/project/pykwalify/

pykwalify

pykwalify





### END MKDOCS TEMPLATE ###

# Markdown extension to wrap images in a lightbox.

# https://github.com/g-provost/lightgallery-markdown

git+https://github.com/g-provost/lightgallery-markdown





# A Mermaid graphs plugin for mkdocs

# https://github.com/fralau/mkdocs-mermaid2-plugin#declaring-the-superfences-extension

mkdocs-mermaid2-plugin



# A MkDocs plugin for dynamic page redirects to prevent broken links.

# https://pypi.org/project/mkdocs-redirects/

mkdocs-redirects

### END MKDOCS TEMPLATE ###

requirements.docs.txt

+41 −8
Original line number Original line Diff line number Diff line
@@ -2,7 +2,6 @@ 
### BEGIN MKDOCS TEMPLATE ###

### BEGIN MKDOCS TEMPLATE ###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###

### Modified content will be overwritten when updating.###

### Modified content will be overwritten when updating.###



#

#

# This file is autogenerated by pip-compile

# This file is autogenerated by pip-compile

# To update, run:

# To update, run:
@@ -11,20 +10,30 @@ 
#

#

astunparse==1.6.3

astunparse==1.6.3

    # via pytkdocs

    # via pytkdocs

babel==2.9.0

babel==2.9.1

    # via mkdocs-git-revision-date-localized-plugin

    # via mkdocs-git-revision-date-localized-plugin

beautifulsoup4==4.9.3

    # via mkdocs-mermaid2-plugin

certifi==2020.12.5

    # via requests

chardet==4.0.0

    # via requests

click==7.1.2

click==7.1.2

    # via

    # via

    #   mkdocs

    #   mkdocs

    #   nltk

    #   nltk

docopt==0.6.2

docopt==0.6.2

    # via pykwalify

    # via pykwalify

editorconfig==0.12.3

    # via jsbeautifier

future==0.18.2

future==0.18.2

    # via lunr

    # via lunr

gitdb==4.0.7

gitdb==4.0.7

    # via gitpython

    # via gitpython

gitpython==3.1.14

gitpython==3.1.14

    # via mkdocs-git-revision-date-localized-plugin

    # via mkdocs-git-revision-date-localized-plugin

idna==2.10

    # via requests

jinja2==2.11.3

jinja2==2.11.3

    # via

    # via

    #   mkdocs

    #   mkdocs
@@ -32,6 +41,10 @@ jinja2==2.11.3 
    #   mkdocstrings

    #   mkdocstrings

joblib==1.0.1

joblib==1.0.1

    # via nltk

    # via nltk

jsbeautifier==1.13.13

    # via mkdocs-mermaid2-plugin

git+https://github.com/g-provost/lightgallery-markdown

    # via -r requirements.docs.in

livereload==2.6.3

livereload==2.6.3

    # via mkdocs

    # via mkdocs

lunr[languages]==0.5.8

lunr[languages]==0.5.8
@@ -40,6 +53,7 @@ markdown-include==0.6.0 
    # via -r requirements.docs.in

    # via -r requirements.docs.in

markdown==3.3.4

markdown==3.3.4

    # via

    # via

    #   lightgallery

    #   markdown-include

    #   markdown-include

    #   mkdocs

    #   mkdocs

    #   mkdocs-autorefs

    #   mkdocs-autorefs
@@ -54,20 +68,25 @@ mkdocs-autorefs==0.1.1 
    # via mkdocstrings

    # via mkdocstrings

mkdocs-exclude==1.0.2

mkdocs-exclude==1.0.2

    # via -r requirements.docs.in

    # via -r requirements.docs.in

mkdocs-git-revision-date-localized-plugin==0.9

mkdocs-git-revision-date-localized-plugin==0.9.2

    # via -r requirements.docs.in

    # via -r requirements.docs.in

mkdocs-macros-plugin==0.5.5

mkdocs-macros-plugin==0.5.5

    # via -r requirements.docs.in

    # via -r requirements.docs.in

mkdocs-material-extensions==1.0.1

mkdocs-material-extensions==1.0.1

    # via mkdocs-material

    # via mkdocs-material

mkdocs-material==7.1.1

mkdocs-material==7.1.4

    # via

    # via

    #   -r requirements.docs.in

    #   -r requirements.docs.in

    #   mkdocs-macros-plugin

    #   mkdocs-macros-plugin

    #   mkdocs-material-extensions

    #   mkdocs-material-extensions

    #   mkdocs-mermaid2-plugin

mkdocs-mermaid2-plugin==0.5.1

    # via -r requirements.docs.in

mkdocs-monorepo-plugin==0.4.14

mkdocs-monorepo-plugin==0.4.14

    # via -r requirements.docs.in

    # via -r requirements.docs.in

mkdocs-section-index==0.2.3

mkdocs-redirects==1.0.3

    # via -r requirements.docs.in

mkdocs-section-index==0.3.0

    # via -r requirements.docs.in

    # via -r requirements.docs.in

mkdocs==1.1.2

mkdocs==1.1.2

    # via

    # via
@@ -77,20 +96,23 @@ mkdocs==1.1.2 
    #   mkdocs-git-revision-date-localized-plugin

    #   mkdocs-git-revision-date-localized-plugin

    #   mkdocs-macros-plugin

    #   mkdocs-macros-plugin

    #   mkdocs-material

    #   mkdocs-material

    #   mkdocs-mermaid2-plugin

    #   mkdocs-monorepo-plugin

    #   mkdocs-monorepo-plugin

    #   mkdocs-redirects

    #   mkdocs-section-index

    #   mkdocs-section-index

    #   mkdocstrings

    #   mkdocstrings

mkdocstrings==0.15.0

mkdocstrings==0.15.0

    # via -r requirements.docs.in

    # via -r requirements.docs.in

nltk==3.6.1

nltk==3.6.2

    # via lunr

    # via lunr

pygments==2.8.1

pygments==2.9.0

    # via mkdocs-material

    # via mkdocs-material

pykwalify==1.8.0

pykwalify==1.8.0

    # via -r requirements.docs.in

    # via -r requirements.docs.in

pymdown-extensions==8.1.1

pymdown-extensions==8.1.1

    # via

    # via

    #   mkdocs-material

    #   mkdocs-material

    #   mkdocs-mermaid2-plugin

    #   mkdocstrings

    #   mkdocstrings

python-dateutil==2.8.1

python-dateutil==2.8.1

    # via

    # via
@@ -104,20 +126,27 @@ pyyaml==5.4.1 
    # via

    # via

    #   mkdocs

    #   mkdocs

    #   mkdocs-macros-plugin

    #   mkdocs-macros-plugin

    #   mkdocs-mermaid2-plugin

regex==2021.4.4

regex==2021.4.4

    # via nltk

    # via nltk

requests==2.25.1

    # via mkdocs-mermaid2-plugin

ruamel.yaml.clib==0.2.2

ruamel.yaml.clib==0.2.2

    # via ruamel.yaml

    # via ruamel.yaml

ruamel.yaml==0.17.4

ruamel.yaml==0.17.4

    # via pykwalify

    # via pykwalify

six==1.15.0

six==1.16.0

    # via

    # via

    #   astunparse

    #   astunparse

    #   jsbeautifier

    #   livereload

    #   livereload

    #   lunr

    #   lunr

    #   mkdocs-redirects

    #   python-dateutil

    #   python-dateutil

smmap==4.0.0

smmap==4.0.0

    # via gitdb

    # via gitdb

soupsieve==2.2.1

    # via beautifulsoup4

termcolor==1.1.0

termcolor==1.1.0

    # via mkdocs-macros-plugin

    # via mkdocs-macros-plugin

tornado==6.1

tornado==6.1
@@ -126,8 +155,12 @@ tornado==6.1 
    #   mkdocs

    #   mkdocs

tqdm==4.60.0

tqdm==4.60.0

    # via nltk

    # via nltk

urllib3==1.26.4

    # via requests

wheel==0.36.2

wheel==0.36.2

    # via astunparse

    # via astunparse





# The following packages are considered to be unsafe in a requirements file:

# setuptools

### END MKDOCS TEMPLATE ###

### END MKDOCS TEMPLATE ###

setup.sh

+23 −16
Original line number Original line Diff line number Diff line
@@ -556,8 +556,9 @@ EOM 
      esac

      esac

      begin="${prefix} ${begin_tag} ${suffix}"

      begin="${prefix} ${begin_tag} ${suffix}"

      end="${prefix} ${end_tag} ${suffix}"

      end="${prefix} ${end_tag} ${suffix}"

      warning="${prefix} WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !${suffix}\n"

      warning="\

      warning+="${prefix} Modified content will be overwritten when updating.${suffix}\n"

${prefix} WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !${suffix}

${prefix} Modified content will be overwritten when updating.${suffix}"





      for i_file in "${tmp_file_from}" "${tmp_file_to}"

      for i_file in "${tmp_file_from}" "${tmp_file_to}"

      do

      do
@@ -571,11 +572,12 @@ EOM 
      then

      then

        if ! grep "${begin}" "${file_from}" &>/dev/null

        if ! grep "${begin}" "${file_from}" &>/dev/null

        then

        then

          content="${begin}\n"

          content="\

          content+="${warning}\n"

${begin}

          content+="$(cat "${file_from}")"

${warning}

          content+="\n\n${end}"

$(cat "${file_from}")

          echo -e "${content}" > "${tmp_file_from}"

${end}"

          echo "${content}" > "${tmp_file_from}"

        else

        else

          sed -n -e "/${begin_tag}/,/${end_tag}/"p "${file_from}" > "${tmp_file_from}"

          sed -n -e "/${begin_tag}/,/${end_tag}/"p "${file_from}" > "${tmp_file_from}"

        fi

        fi
@@ -591,6 +593,7 @@ EOM 
          fi

          fi

          cp "${file_to}" "${bak_file}"

          cp "${file_to}" "${bak_file}"





          mkdocs_log "INFO" "Upgrading file **${relative_file_to}**."

          grep -B 1000000 "${begin}" "${file_to}" | sed -e "s/${begin}//g" > "${tmp_file_to}"

          grep -B 1000000 "${begin}" "${file_to}" | sed -e "s/${begin}//g" > "${tmp_file_to}"

          cat "${tmp_file_from}" >> "${tmp_file_to}"

          cat "${tmp_file_from}" >> "${tmp_file_to}"

          grep -A 1000000 "${end}" "${file_to}" | sed -e "s/${end}//g" >> "${tmp_file_to}"

          grep -A 1000000 "${end}" "${file_to}" | sed -e "s/${end}//g" >> "${tmp_file_to}"
@@ -639,6 +642,8 @@ EOM 
    local relative_file_to="${file_to##*${MKDOCS_ROOT}\/}"

    local relative_file_to="${file_to##*${MKDOCS_ROOT}\/}"

    local begin=""

    local begin=""

    local end=""

    local end=""

    local begin_tag="BEGIN MKDOCS TEMPLATE"

    local end_tag="END MKDOCS TEMPLATE"

    local warning=""

    local warning=""

    local prefix=""

    local prefix=""

    local suffix=""

    local suffix=""
@@ -661,17 +666,19 @@ EOM 
            suffix="###"

            suffix="###"

          ;;

          ;;

      esac

      esac

      begin="${prefix} BEGIN MKDOCS TEMPLATE ${suffix}"

      begin="${prefix} ${begin_tag} ${suffix}"

      end="${prefix} END MKDOCS TEMPLATE ${suffix}"

      end="${prefix} ${end_tag} ${suffix}"

      warning="${prefix} WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !${suffix}\n"

      warning="\

      warning+="${prefix} Modified content will be overwritten when updating.${suffix}\n"

${prefix} WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !${suffix}

${prefix} Modified content will be overwritten when updating.${suffix}"

      if [[ -n "${prefix}" ]] && ! grep "${begin}" "${file_from}" &>/dev/null

      if [[ -n "${prefix}" ]] && ! grep "${begin}" "${file_from}" &>/dev/null

      then

      then

        content="${begin}\n"

          content="\

        content+="${warning}\n"

${begin}

        content+="$(cat "${file_from}")"

${warning}

        content+="\n\n${end}"

$(cat "${file_from}")

        echo -e "${content}" > "${file_to}"

${end}"

        echo "${content}" > "${file_to}"

      else

      else

        cp "${file_from}" "${file_to}"

        cp "${file_from}" "${file_to}"

      fi

      fi

templates/docs/_data/plugins.py

+94 −46
Original line number Original line Diff line number Diff line 
#!/usr/bin/env python3

#!/usr/bin/env python3

"""

"""Set of methods to manage mkdocs configuration dynamically.



Set of methods for

Set of methods for

[mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) Set of

[mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) Set of

which :

which :
@@ -99,6 +100,7 @@ def add_internal_to_nav( 
    """

    """

    if nav_parent:

    if nav_parent:

        for i_nav in nav:

        for i_nav in nav:

            # "nav_entry" is a key of current parsed `nav`

            if nav_parent[0] in i_nav:

            if nav_parent[0] in i_nav:

                for i_key in i_nav:

                for i_key in i_nav:

                    add_internal_to_nav(

                    add_internal_to_nav(
@@ -108,6 +110,16 @@ def add_internal_to_nav( 
                        repo_parent,

                        repo_parent,

                        nav_parent[1:],

                        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:

    else:

        mkdocs_path = env.project_dir

        mkdocs_path = env.project_dir

        for i_parent in repo_parent:

        for i_parent in repo_parent:
@@ -152,6 +164,14 @@ def add_external_to_nav( 
                        repo_parent,

                        repo_parent,

                        nav_parent[1:],

                        nav_parent[1:],

                    )

                    )

    elif repo_dict["online_url"].startswith("/"):

        nav.append(

            {

                repo_dict["nav_entry"]: repo_dict["online_url"].replace(

                    "/", "../", 1

                )

            }

        )

    else:

    else:

        nav.append({repo_dict["nav_entry"]: repo_dict["online_url"]})

        nav.append({repo_dict["nav_entry"]: repo_dict["online_url"]})
@@ -224,12 +244,14 @@ def update_nav( 
            nav_parent.append(repo_dict["nav_entry"])

            nav_parent.append(repo_dict["nav_entry"])

        elif i_key == "internal":

        elif i_key == "internal":

            for i_repo in repo_dict["internal"]:

            for i_repo in repo_dict["internal"]:

                if nav_parent[0] not in yaml.dump(env.conf["nav"]):

                    add_nav_entry(env.conf["nav"], nav_parent)

                    add_nav_entry(env.conf["nav"], nav_parent)

                add_internal_to_nav(

                add_internal_to_nav(

                    env, env.conf["nav"], i_repo, repo_parent, nav_parent

                    env, env.conf["nav"], i_repo, repo_parent, nav_parent

                )

                )

        elif i_key == "external":

        elif i_key == "external":

            for i_repo in repo_dict["external"]:

            for i_repo in repo_dict["external"]:

                if nav_parent[0] not in yaml.dump(env.conf["nav"]):

                    add_nav_entry(env.conf["nav"], nav_parent)

                    add_nav_entry(env.conf["nav"], nav_parent)

                add_external_to_nav(

                add_external_to_nav(

                    env, env.conf["nav"], i_repo, repo_parent, nav_parent

                    env, env.conf["nav"], i_repo, repo_parent, nav_parent
@@ -400,9 +422,16 @@ def set_copyright(env: dict, git_repo: git.Repo) -> None: 
            first_year = time.strftime("%Y", time.localtime())

            first_year = time.strftime("%Y", time.localtime())

        curr_year = time.strftime("%Y", time.localtime())

        curr_year = time.strftime("%Y", time.localtime())





        if first_year == curr_year:

            env.variables["date_copyright"] = f"Copyright &copy; {curr_year}"

        else:

            env.variables[

                "date_copyright"

            ] = f"Copyright &copy; {curr_year} - {curr_year}"



        env.conf[

        env.conf[

            "copyright"

            "copyright"

        ] = f"Copyright &copy; {first_year} - {curr_year} {env.variables['copyright']}"

        ] = f"{env.variables['date_copyright']} {env.variables['copyright']}"









def set_repo_name(env: dict, repo_slug: str) -> None:

def set_repo_name(env: dict, repo_slug: str) -> None:
@@ -424,7 +453,6 @@ def set_repo_name(env: dict, repo_slug: str) -> None: 
        env: Mkdocs macro plugin environment dictionary.

        env: Mkdocs macro plugin environment dictionary.

        repo_slug: Repo slug or name of the repo folder.

        repo_slug: Repo slug or name of the repo folder.

    """

    """



    if "repo_name" not in env.conf or not env.conf["repo_name"]:

    if "repo_name" not in env.conf or not env.conf["repo_name"]:

        if "repo_name" in env.variables:

        if "repo_name" in env.variables:

            env.conf["repo_name"] = env.variables["repo_name"]

            env.conf["repo_name"] = env.variables["repo_name"]
@@ -533,7 +561,6 @@ def set_config(env: dict) -> None: 
    Arguments:

    Arguments:

        env: Mkdocs macro plugin environment dictionary.

        env: Mkdocs macro plugin environment dictionary.

    """

    """



    git_repo = git.Repo(search_parent_directories=True)

    git_repo = git.Repo(search_parent_directories=True)

    repo_slug = get_repo_slug(env, git_repo)

    repo_slug = get_repo_slug(env, git_repo)
@@ -548,7 +575,7 @@ def set_config(env: dict) -> None: 




    if "subrepo" in env.variables:

    if "subrepo" in env.variables:

        if (

        if (

            env.variables["internal_subdoc"]

            not env.variables["internal_subdoc"]

            and "monorepo" in env.conf["plugins"]

            and "monorepo" in env.conf["plugins"]

        ):

        ):

            env.conf["plugins"].pop("monorepo")

            env.conf["plugins"].pop("monorepo")
@@ -557,7 +584,7 @@ def set_config(env: dict) -> None: 








def load_yaml_file(path: str, filename: str) -> None:

def load_yaml_file(path: str, filename: str) -> None:

    """Ensure a YAML file is valid again a schema and return its content

    """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

    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.

    validate its content. If content is not valid, an error will be raised.
@@ -602,7 +629,7 @@ def update_subrepo_logo_src( 
    path: str,

    path: str,

    external: bool,

    external: bool,

) -> None:

) -> None:

    """Update the content of the key `logo` and `src_path` of subrepo

    """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

    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

    from file `docs/_data/repo.yaml` in the cloned subrepo, relative to the main
@@ -669,7 +696,7 @@ def update_subrepo_info( 
                f"{INFO_CLR}INFO [macros] - Pulling repo {i_repo['name']}{RESET_CLR}"

                f"{INFO_CLR}INFO [macros] - Pulling repo {i_repo['name']}{RESET_CLR}"

            )

            )

            git_subrepo = git.Repo(subrepo_root)

            git_subrepo = git.Repo(subrepo_root)

            git_subrepo.remotes.origin.pull()

            git_subrepo.remotes.origin.pull('master')

        else:

        else:

            print(

            print(

                f"{INFO_CLR}INFO [macros] - Cloning repo {i_repo['name']}{RESET_CLR}"

                f"{INFO_CLR}INFO [macros] - Cloning repo {i_repo['name']}{RESET_CLR}"
@@ -740,7 +767,7 @@ def update_subrepo( 
def update_logo_src_repo(

def update_logo_src_repo(

    env: dict, curr_repo: dict, repo_name: str, path: str = None

    env: dict, curr_repo: dict, repo_name: str, path: str = None

) -> None:

) -> None:

    """Update the content of the key `logo` and `src_path` of current repo

    """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

    Update value of keys `logo` and `src_path` of current repo holding the

    documentation.

    documentation.
@@ -753,7 +780,6 @@ def update_logo_src_repo( 
        repo_name: Name of the repo,

        repo_name: Name of the repo,

        path: Absolute path of the location of the current repo.

        path: Absolute path of the location of the current repo.

    """

    """



    subpath = ""

    subpath = ""

    if path:

    if path:

        subpath = os.path.join(path.replace(env.project_dir, ""), repo_name)

        subpath = os.path.join(path.replace(env.project_dir, ""), repo_name)
@@ -771,7 +797,7 @@ def update_logo_src_repo( 








def load_var_file(env: dict) -> None:

def load_var_file(env: dict) -> None:

    """Load variables files in `docs/_data/`

    """Load variables files in `docs/_data/`.





    Load every yaml files in `docs/_data/`, if one of the file define the

    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.

    current repo, then update keys `logo` and `src_path` for the current repo.
@@ -792,7 +818,7 @@ def load_var_file(env: dict) -> None: 








def update_version(env: dict) -> None:

def update_version(env: dict) -> None:

    """Parse every tags of the repo to build a `docs/versions.json`

    """Parse every tags of the repo to build a `docs/versions.json`.





    To emulate mike version support for gitlab, this method will parse every

    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

    tags of the current repo holding the current documentation to create a file
@@ -812,45 +838,51 @@ def update_version(env: dict) -> None: 
        return

        return

    git_repo = git.Repo(search_parent_directories=True)

    git_repo = git.Repo(search_parent_directories=True)

    mike_version = list()

    mike_version = list()

    last_major = 0

    last_major = -1

    last_minor = 0

    last_minor = -1

    last_patch = 0

    last_patch = str(-1)

    for i_tag in git_repo.tags:

    for i_tag in git_repo.tags:

        i_tag = yaml.dump(i_tag.path)

        i_tag = yaml.dump(i_tag.path)

        i_tag = re.sub(".*v", "", i_tag).split(".")

        i_tag = re.sub(".*v", "", i_tag).split(".")

        major = int(i_tag[0])

        major = int(i_tag[0])

        minor = int(i_tag[1])

        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 major > last_major:

            if last_major >= 0:

                mike_version.append(

                mike_version.append(

                    {

                    {

                    "version": "{}.{}".format(last_major, last_minor),

                        "version": f"{last_major}.{last_minor}",

                    "title": "{}.{}.{}".format(

                        "title": f"{last_major}.{last_minor}.{last_patch}",

                        last_major, last_minor, last_patch

                    ),

                        "aliases": [],

                        "aliases": [],

                    }

                    }

                )

                )

            last_major = major

            last_major = major

            last_minor = 0

            last_minor = -1

        if minor > last_minor:

        if minor > last_minor:

            if last_minor >= 0:

                mike_version.append(

                mike_version.append(

                    {

                    {

                    "version": "{}.{}".format(last_major, last_minor),

                        "version": f"{last_major}.{last_minor}",

                    "title": "{}.{}.{}".format(

                        "title": f"{last_major}.{last_minor}.{last_patch}",

                        last_major, last_minor, last_patch

                    ),

                        "aliases": [],

                        "aliases": [],

                    }

                    }

                )

                )

            last_minor = minor

            last_minor = minor

            last_patch = 0

            last_patch = str(-1)

        if patch > last_patch:

        if patch > last_patch:

            last_patch = patch

            last_patch = str(patch)



    mike_version.append(

    mike_version.append(

        {

        {

            "version": "{}.{}".format(last_major, last_minor),

            "version": f"{last_major}.{last_minor}",

            "title": "{}.{}.{}".format(last_major, last_minor, last_patch),

            "title": f"{last_major}.{last_minor}.{last_patch}",

            "aliases": ["latest"],

            "aliases": ["latest"],

        }

        }

    )

    )
@@ -864,7 +896,8 @@ def update_version(env: dict) -> None: 
def define_env(env: dict) -> None:

def define_env(env: dict) -> None:

    # pylint: disable=C0301

    # pylint: disable=C0301

    # - C0301: Line to long

    # - C0301: Line to long

    """

    """Hook for mkdocs-macros-plugins defining variables, macros and filters.



    This is the hook for defining variables, macros and filters

    This is the hook for defining variables, macros and filters





    - variables: the dictionary that contains the environment variables

    - variables: the dictionary that contains the environment variables
@@ -879,7 +912,6 @@ def define_env(env: dict) -> None: 
    Arguments:

    Arguments:

        env: Mkdocs macro plugin environment dictionary.

        env: Mkdocs macro plugin environment dictionary.

    """

    """



    load_var_file(env)

    load_var_file(env)





    if "subrepo" in env.variables:

    if "subrepo" in env.variables:
@@ -898,14 +930,30 @@ def define_env(env: dict) -> None: 
    # pylint: disable=W0612

    # pylint: disable=W0612

    # -  W0612: Unused variable (unused-variable)

    # -  W0612: Unused variable (unused-variable)

    def subs(var: str) -> dict:

    def subs(var: str) -> dict:

        """Return the content of the dictionary defined by var"""

        """Return the content of the dictionary defined by var.



        Arguments:

            var: Key in env.variables to return.



        Returns:

            The value of `env.variables[var]` if it exists, else return None.

        """

        if var in env.variables:

            return env.variables[var]

            return env.variables[var]

        return None





    @env.macro

    @env.macro

    # pylint: disable=W0612

    # pylint: disable=W0612

    # -  W0612: Unused variable (unused-variable)

    # -  W0612: Unused variable (unused-variable)

    def to_html(var: str) -> dict:

    def to_html(var: str) -> dict:

        """Convert the content of the markdown string into HTML"""

        """Convert the content of the markdown string into HTML.



        Arguments:

            var: Markdown string which need to be converted to HTML



        Returns:

            The content of the markdown converted to HTML

        """

        return markdown.markdown(var)

        return markdown.markdown(var)

templates/docs/_data/template/repo.tpl.yaml

+5 −3
Original line number Original line Diff line number Diff line
@@ -26,11 +26,13 @@ repo_name: 




  # (OPTIONAL) Path, relative to `docs_dir` mkdocs config, to the logo of the

  # (OPTIONAL) Path, relative to `docs_dir` mkdocs config, to the logo of the

  # repo. If not specified, path will automatically be set to

  # repo. If not specified, path will automatically be set to

  # `assets/img/meta/reop_name_logo.png`

  # `assets/img/meta/repo_name_logo.png`

  #logo: "assets/img/meta/repo_template_logo.png"

  #logo: "assets/img/meta/repo_name_logo.png"

  # Description of the repo, will be used to setup the mkdocs description.

  # Description of the repo, will be used to setup the mkdocs description.

  desc: >-

  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

  # (OPTIONAL) If you plan to use `mkdocstring` plugins to render python

  # source code, you will need to provide the path where your source files

  # source code, you will need to provide the path where your source files

templates/docs/_data/template/subrepo.tpl.yaml

+8 −0
Original line number Original line Diff line number Diff line
@@ -22,6 +22,10 @@ subrepo: 
  #     - name: subrepo_1

  #     - name: subrepo_1

  #       # SSH or HTTP link to the online subrepo_1

  #       # SSH or HTTP link to the online subrepo_1

  #       git_url: git@domain.tld:namesapce/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

  #   # List of subdirectory from `dir_name` which are repos with

  #   # mkdocs documentation which will be included in the documentation.

  #   # mkdocs documentation which will be included in the documentation.

  #   external:

  #   external:
@@ -31,6 +35,10 @@ subrepo: 
  #     - name: subrepo_2

  #     - name: subrepo_2

  #       # SSH or HTTP link to the online subrepo_2

  #       # SSH or HTTP link to the online subrepo_2

  #       git_url: git@domain.tld:namesapce/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

  #   # Another sub dir_name which also old subrepos

  #   subdir_name:

  #   subdir_name:

  #     nav_entry: "Sub Nav Entry"

  #     nav_entry: "Sub Nav Entry"

templates/requirements.docs.txt

+7 −7
Original line number Original line Diff line number Diff line
@@ -6,7 +6,7 @@ 
#

#

astunparse==1.6.3

astunparse==1.6.3

    # via pytkdocs

    # via pytkdocs

babel==2.9.0

babel==2.9.1

    # via mkdocs-git-revision-date-localized-plugin

    # via mkdocs-git-revision-date-localized-plugin

click==7.1.2

click==7.1.2

    # via

    # via
@@ -49,20 +49,20 @@ mkdocs-autorefs==0.1.1 
    # via mkdocstrings

    # via mkdocstrings

mkdocs-exclude==1.0.2

mkdocs-exclude==1.0.2

    # via -r requirements.docs.in

    # via -r requirements.docs.in

mkdocs-git-revision-date-localized-plugin==0.9

mkdocs-git-revision-date-localized-plugin==0.9.2

    # via -r requirements.docs.in

    # via -r requirements.docs.in

mkdocs-macros-plugin==0.5.5

mkdocs-macros-plugin==0.5.5

    # via -r requirements.docs.in

    # via -r requirements.docs.in

mkdocs-material-extensions==1.0.1

mkdocs-material-extensions==1.0.1

    # via mkdocs-material

    # via mkdocs-material

mkdocs-material==7.1.1

mkdocs-material==7.1.4

    # via

    # via

    #   -r requirements.docs.in

    #   -r requirements.docs.in

    #   mkdocs-macros-plugin

    #   mkdocs-macros-plugin

    #   mkdocs-material-extensions

    #   mkdocs-material-extensions

mkdocs-monorepo-plugin==0.4.14

mkdocs-monorepo-plugin==0.4.14

    # via -r requirements.docs.in

    # via -r requirements.docs.in

mkdocs-section-index==0.2.3

mkdocs-section-index==0.3.0

    # via -r requirements.docs.in

    # via -r requirements.docs.in

mkdocs==1.1.2

mkdocs==1.1.2

    # via

    # via
@@ -77,9 +77,9 @@ mkdocs==1.1.2 
    #   mkdocstrings

    #   mkdocstrings

mkdocstrings==0.15.0

mkdocstrings==0.15.0

    # via -r requirements.docs.in

    # via -r requirements.docs.in

nltk==3.6.1

nltk==3.6.2

    # via lunr

    # via lunr

pygments==2.8.1

pygments==2.9.0

    # via mkdocs-material

    # via mkdocs-material

pykwalify==1.8.0

pykwalify==1.8.0

    # via -r requirements.docs.in

    # via -r requirements.docs.in
@@ -105,7 +105,7 @@ ruamel.yaml.clib==0.2.2 
    # via ruamel.yaml

    # via ruamel.yaml

ruamel.yaml==0.17.4

ruamel.yaml==0.17.4

    # via pykwalify

    # via pykwalify

six==1.15.0

six==1.16.0

    # via

    # via

    #   astunparse

    #   astunparse

    #   livereload

    #   livereload