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 18

22 files
+ 280
201
Compare changes
  • Side-by-side
  • Inline

Files

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

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

Template to easily setup and managed [mkdocs][mkdocs] documentation in folder
to have homogenous documentation.
Mkdocs Templates scaffolding project to host documentation configuration
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
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.
project 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
I had to go to each project 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
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
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
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
@@ -169,4 +169,4 @@ You can now browse the full documentation by visiting

<!-- 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
Original line number Diff line number Diff line
@@ -2,7 +2,7 @@
example:
  my_repo_slug:
    name: My Main Repo Name
    desc: Description of my [Main Repo](#)
    desc: Description of my [Main Repo]()
  subrepo:
    roles:
      nav_entry: "Roles"
Original line number Diff line number Diff line
@@ -153,6 +153,10 @@ def add_external_to_nav(
                        repo_parent,
                        nav_parent[1:],
                    )
    elif repo_dict["online_url"].startswith('/'):
        nav.append({
            repo_dict["nav_entry"]: repo_dict["online_url"].replace('/','../',1)
        })
    else:
        nav.append({repo_dict["nav_entry"]: repo_dict["online_url"]})

@@ -822,21 +826,26 @@ def update_version(env: dict) -> None:
    mike_version = list()
    last_major = -1
    last_minor = -1
    last_patch = -1
    last_patch = str(-1)
    for i_tag in git_repo.tags:
        i_tag = yaml.dump(i_tag.path)
        i_tag = re.sub(".*v", "", i_tag).split(".")
        major = int(i_tag[0])
        minor = int(i_tag[1])
        patch = int(i_tag[2])
        patch = str()
        for i_remain_tag in i_tag[2:]:
            if i_remain_tag and i_remain_tag not in ("","\n"):
                i_remain_tag = i_remain_tag.replace("\n","")
                if not patch:
                    patch = f"{i_remain_tag}"
                else:
                    patch = f"{patch}.{i_remain_tag}"
        if major > last_major:
            if last_major >= 0:
                mike_version.append(
                    {
                        "version": "{}.{}".format(last_major, last_minor),
                        "title": "{}.{}.{}".format(
                            last_major, last_minor, last_patch
                        ),
                        "version": f"{last_major}.{last_minor}",
                        "title": f"{last_major}.{last_minor}.{last_patch}",
                        "aliases": [],
                    }
                )
@@ -846,21 +855,20 @@ def update_version(env: dict) -> None:
            if last_minor >= 0:
                mike_version.append(
                    {
                        "version": "{}.{}".format(last_major, last_minor),
                        "title": "{}.{}.{}".format(
                            last_major, last_minor, last_patch
                        ),
                        "version": f"{last_major}.{last_minor}",
                        "title": f"{last_major}.{last_minor}.{last_patch}",
                        "aliases": [],
                    }
                )
            last_minor = minor
            last_patch = -1
            last_patch = str(-1)
        if patch > last_patch:
            last_patch = patch
            last_patch = str(patch)

    mike_version.append(
        {
            "version": "{}.{}".format(last_major, last_minor),
            "title": "{}.{}.{}".format(last_major, last_minor, last_patch),
            "version": f"{last_major}.{last_minor}",
            "title": f"{last_major}.{last_minor}.{last_patch}",
            "aliases": ["latest"],
        }
    )
@@ -914,9 +922,11 @@ def define_env(env: dict) -> None:
            var: Key in env.variables to return.

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

    @env.macro
    # pylint: disable=W0612
Original line number Diff line number Diff line

### BEGIN MKDOCS TEMPLATE ###
### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###
### Modified content will be overwritten when updating.###
@@ -29,11 +30,13 @@ repo_name:

  # (OPTIONAL) Path, relative to `docs_dir` mkdocs config, to the logo of the
  # repo. If not specified, path will automatically be set to
  # `assets/img/meta/reop_name_logo.png`
  #logo: "assets/img/meta/repo_template_logo.png"
  # `assets/img/meta/repo_name_logo.png`
  #logo: "assets/img/meta/repo_name_logo.png"
  # Description of the repo, will be used to setup the mkdocs description.
  desc: >-
    Repo description with markdown support
    An explicit description to explain what my repo do. Can be a multiline
    description with **markdown** support such as
    [link](https://url.domain.tld) and more.

  # (OPTIONAL) If you plan to use `mkdocstring` plugins to render python
  # source code, you will need to provide the path where your source files
@@ -47,3 +50,4 @@ repo_name:
    - name: "Firstname Lastname"
      mail: "mail@domain.tld"
### END MKDOCS TEMPLATE ###
Original line number Diff line number Diff line

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


<!-- BEGIN MKDOCS TEMPLATE -->
<!--
WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !
@@ -40,9 +41,9 @@ my projects. There you will find:
  * [Contributing workflow][contributing_workflow], which provide an example
   of the workflow I used for the development.

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

## Community

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

<!-- END MKDOCS TEMPLATE -->
Original line number Diff line number Diff line
@@ -10,6 +10,18 @@ Modified content will be overwritten when updating

## 🔖 v1.0

### 🔖 v1.0.3 <small>(13/05/2021)</small>

- 📝 Update documentation content.
- 🔧 Update extra content through yaml `_data·` files
    - Add new content
    - Add documentation in template files
- ✨ Improve `plugins.py` behaviour
    - Convert `.format()` string into `f""` string
    - Fix configuration management
- ⬆📌 Upgrade pinned python dependencies


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

- 📝📄 Update copyright in license content
Original line number Diff line number Diff line
@@ -15,7 +15,8 @@ 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 from your accessible namespace:
Then, choose where you want to store your fork in one of your accessible
namespaces:

![!Fork Mkdocs Template Destination][fork_mkdocs_template_dest]

@@ -44,20 +45,21 @@ git clone git@gitdomain.tld:namespace/mkdocs_template.git.

## Add the content of your template

Now, to setup your own template, you just have to write it in the empty folder
but track `user_config` folder. If you happen to add a file with the same path
from `template`, the your file will override the one in `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.
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 exaple. 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. files.
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`"

@@ -398,7 +400,7 @@ git remote -v
> origin <URL_TO_YOUR_ORIGIN_REMOTE> (push)
```

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

```bash
git remote add upstream {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}.git
Original line number Diff line number Diff line
{% set curr_repo=subs("mkdocs_template") %}
# Example

This current documentation you are reading is actually using the custom template
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 :
@@ -22,12 +22,10 @@ This custom template add a lots of things such as :
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]
Original line number Diff line number Diff line
@@ -4,9 +4,10 @@ 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] or
provide a basic README.md as well as licenses or a default file
`docs/_data/vars.yml` for all your documentation.
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:
Original line number 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
the folder that will host the documenation and render a preview of such
basic documenation based from template.
basic documentation based from template.

This will be done by creating symlinks from `templates` and `user_config`
folders into `preview` folder.

Available options are:

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

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

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



## main()

 **Setup folder to be able to use directory environment mechanism**
 **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
 mkdocs documentation.
 
 If directory already set to use directory environment, then check if user
 explicitly tell to upgrade and upgrade, otherwise, print a warning and exit.
 
 If directory not already set to use directory environment, clone
 user provided repo to a temporary folder, copy relevant scripts, files and
 folders to initiliaze a documentation rendered using mkdocs.
 Build the list of the file that will be installed if using the mkdocs
 documentation template, make a symlinks of all these files into `preview`
 folder and, depending on the options provided, render the documentation
 preview.

 **Globals**

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

 | Arguments | Description |
 | :-------- | :---------- |
 | `-u,--upgrade` | -u,--upgrade |
 | `-r,--repo-url REPO_URL` | -r,--repo-url REPO_URL |
 | `-s,--subrepo` | -s,--subrepo |
 | `-c,--clean`      |  Remove every existing symlinks before rendering the preview. |
 | `-r,--very-clean` |  Remove every existing symlinks without rendering the preview. |
 | `-h,--help`       |  Print this help. |

 **Output**

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

 **Returns**

 - 0 if directory is correctly configure to start writing documentation
 - 1 if something when wrong during the setup of documentation
 - 0, if rendering of the preview documentation went right.
 - 1, if rendering of the preview documentation went wrong.

### manpage()

> **Extract the script documentation from header and print it on stdout**
> **Extract the script documentation from header and print it on stdout.**
>
> Simply extract the docstring from the header of the script, format it with
> some output enhancement (such as bold) and print it to stdout.
@@ -86,7 +81,7 @@ Available options are:

### mkdocs_log()

> **Print debug message in colors depending on message severity on stderr**
> **Print debug message in colors depending on message severity on stderr.**
>
> Echo colored log depending on user provided message severity. Message
> severity are associated to following color output:
@@ -128,18 +123,19 @@ Available options are:
>
> | Arguments | Description |
> | :-------- | :---------- |
> | `$1, string, absolute path to the folder which will be parsed` | $1, string, absolute path to the folder which will be parsed |
> | `$1` |  string, absolute path to the folder which will be parsed |
>
>

### build_final_file_list()

> **Replate templates file by user configured files**
> **Build the merged list from `templates` and `user_config` folder.**
>
> If there is the same file in `user_config` and `templates` folder, then
> replace the file to be installed from `templates` by the one in
> `user_config`. Finally, add remaining `user_config` files not in
> `templates` to the list of files to install or upgrade in a bash array.
> `templates` to the list of files to install or upgrade in a bash array set
> in parent method.
>
> **Globals**
>
@@ -151,6 +147,7 @@ Available options are:

> **Recursively clean the preview folder by removing all symlinks**
>
> Simply remove recursively all symlinks from folder `preview`.
>
> **Globals**
>
@@ -165,11 +162,11 @@ Available options are:

### setup_mkdocs()

> **Recursively install base folder and script to write mkdocs documentation.**
> **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
> their right location from the temporary clone repo to the folder which
> will host the mkdocs documentation.
> Build the list of files and folders, recursively create a symlink of all
> files to their right location from the temporary clone repo to the folder
> `preview`.
>
> **Globals**
>
Original line number Diff line number Diff line
# Configuration of the documentation

Once you have install files using the script `setup.sh`, and before starting to
render your documentation you will need some configuration to do:
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 normally done in `mkdocs.yml` file,
but to be able to use a templated `mkdocs.yml`, most of the configuration is
handled differently.
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
@@ -25,7 +25,8 @@ 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 repo information.
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/

@@ -33,10 +34,10 @@ automatically set based on the repo information.

!!! 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.
    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).
@@ -50,8 +51,9 @@ cp docs/_data/template/repo.tpl.yaml docs/_data/my_repo_slug.yaml
vim docs/_data/my_repo_slug.yaml
```

You will need to update some key of the repo which will be used to automatically
set `mkdocs.yml` configuration if not set in `docs/_data/vars.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`.
@@ -87,13 +89,14 @@ my_repo_slug:

  # (OPTIONAL) Path, relative to `docs_dir` mkdocs config, to the logo of the
  # repo. If not specified, path will automatically be set to
  # `assets/img/meta/reop_name_logo.png`
  #logo: "assets/img/meta/repo_template_logo.png"
  # `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)
    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
@@ -111,16 +114,17 @@ my_repo_slug:
## Subrepo Variables

If you are working on a big project, with multiple subrepo you might have or
want to split a documentation per project but render all of them from a master
repository.
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 file and folders holdings
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 collection.
But you want the final rendered documentation to include these repos.
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.
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`.

@@ -158,13 +162,14 @@ subrepo:
          git_url: https://gitdomain.tld/namespace/subnamespace/my_role_name_2
```

If you want to add link to external documentation, i.e. they will be included in
the `nav` of the main repo but their own `nav` will not be include, this can
also be done with the file `docs/_data/subrepo.yaml`.
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 repo, 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:
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
@@ -196,7 +201,7 @@ subrepo:
          online_url: https://domain.tld/full/external/link/
```

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

??? Example
@@ -256,22 +261,22 @@ reveal).
    ```

Thus, when rendering the documentation, the script `docs/_data/plugins.py` will
check if folders `roles/{role_name_1,role_name_2}`, 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.
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`
allowing to access to the repo informations.
of each repo allowing to access to the repo informations.


## Extra variables

All of the above file will create variables which can be use in your
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 check
`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
@@ -281,11 +286,11 @@ without schema control.

## Variable usage

Finally, as describe above some variables are used during the rendering of the
documentation. But they can also be use in your markdown documentation files using
jinja. For instance, below is a basic content of a markdown file showing the
name of the repo, its description and a list of roles and programs with their
description.
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"

Original line number Diff line number Diff line
@@ -25,7 +25,7 @@ chmod +x /tmp/setup_mkdocs.sh
```

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:

```bash
# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION
@@ -36,8 +36,8 @@ curl -sfL \
    -r {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}
```

This will automatically copy the content of folder `templates` of the project in
the folder where you are located.
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:
@@ -48,7 +48,7 @@ are not present. For instance, following example content:
Sample content of a page
```

Wille be copied with the following tags:
Will be copied with the following tags:

```md
<!-- BEGIN MKDOCS TEMPLATE -->
@@ -61,15 +61,15 @@ Sample content of a page
<!-- END MKDOCS TEMPLATE -->
```

These tags serve as delimiter of the template content, without theme, any
modification you may have done on copied file will be overwritten when you will
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 updte.
tags might be updated if latest version contain update.

In other words, you might do the following update:
In other words, you might do the following:

```md
# Previous title
@@ -92,7 +92,7 @@ Content added by the user, which will not be updated in case of upgrade of the
template.
```

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

  - `*.md`, `*.html` or `*LICENSE`, will have following tags:
    ```html
@@ -100,7 +100,7 @@ The tag comment depends of the extension of the file copied:
    <!-- WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! -->
    <!-- Modified content will be overwritten when updating -->

    [...]
    []

    <!-- END MKDOCS TEMPLATE -->
    ```
@@ -111,7 +111,7 @@ The tag comment depends of the extension of the file copied:
    /* WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! */
    /* Modified content will be overwritten when updating */

    [...]
    []

    /* END MKDOCS TEMPLATE */
    ```
@@ -123,16 +123,16 @@ The tag comment depends of the extension of the file copied:
    ### Modified content will be overwritten when updating ###
    ###

    [...]
    []

    ### END MKDOCS TEMPLATE ###
    ```

  - Other extension files will not have comment tags, this is mainly for source
    code file or svg images for instance.
  - Files with other extension will not have comment tags, this is mainly for
    source code file or svg images for instance.


Moreover, is there is already mkdocs tag in the file, the complete file will be
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.

@@ -142,6 +142,6 @@ 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
know have some [configuration][configuration] to do.
now have some [configuration][configuration] to do.

[configuration]: configure.md
Original line number 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 to so is as easy as installing the documentation.
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

@@ -10,11 +10,10 @@ of the usage of the script

## 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.
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
+1 −0
Original line number Diff line number Diff line
@@ -80,6 +80,7 @@ extra_css:
  # 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
Original line number Diff line number Diff line

### BEGIN MKDOCS TEMPLATE ###
### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###
### Modified content will be overwritten when updating.###
@@ -12,11 +11,11 @@ appdirs==1.4.4
    # via
    #   black
    #   virtualenv
astroid==2.5.3
astroid==2.5.6
    # via pylint
attrs==20.3.0
attrs==21.2.0
    # via pytest
black==20.8b1
black==21.5b0
    # via -r requirements.dev.in
click==7.1.2
    # via black
@@ -64,11 +63,11 @@ pydocstyle==6.0.0
    # via -r requirements.dev.in
pyflakes==2.2.0
    # via flake9
pylint==2.7.4
pylint==2.8.2
    # via -r requirements.dev.in
pyparsing==2.4.7
    # via packaging
pytest==6.2.3
pytest==6.2.4
    # via -r requirements.dev.in
pyyaml==5.4.1
    # via yamllint
@@ -76,7 +75,7 @@ regex==2021.4.4
    # via black
shellcheck-py==0.7.2.1
    # via -r requirements.dev.in
six==1.15.0
six==1.16.0
    # via
    #   tox
    #   virtualenv
@@ -88,17 +87,12 @@ toml==0.10.2
    #   pylint
    #   pytest
    #   tox
tox==3.23.0
tox==3.23.1
    # via -r requirements.dev.in
typed-ast==1.4.3
    # via black
typing-extensions==3.7.4.3
    # via black
virtualenv==20.4.4
virtualenv==20.4.6
    # via tox
wrapt==1.12.1
    # via astroid
yamllint==1.26.1
    # via -r requirements.dev.in
### END MKDOCS TEMPLATE ###
Original line number Diff line number Diff line
@@ -56,4 +56,8 @@ 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 ###
Original line number Diff line number Diff line

### BEGIN MKDOCS TEMPLATE ###
### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###
### Modified content will be overwritten when updating.###
@@ -9,7 +10,7 @@
#
astunparse==1.6.3
    # via pytkdocs
babel==2.9.0
babel==2.9.1
    # via mkdocs-git-revision-date-localized-plugin
beautifulsoup4==4.9.3
    # via mkdocs-mermaid2-plugin
@@ -67,13 +68,13 @@ mkdocs-autorefs==0.1.1
    # via mkdocstrings
mkdocs-exclude==1.0.2
    # 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
mkdocs-macros-plugin==0.5.5
    # via -r requirements.docs.in
mkdocs-material-extensions==1.0.1
    # via mkdocs-material
mkdocs-material==7.1.1
mkdocs-material==7.1.4
    # via
    #   -r requirements.docs.in
    #   mkdocs-macros-plugin
@@ -83,7 +84,9 @@ mkdocs-mermaid2-plugin==0.5.1
    # via -r requirements.docs.in
mkdocs-monorepo-plugin==0.4.14
    # 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
mkdocs==1.1.2
    # via
@@ -95,13 +98,14 @@ mkdocs==1.1.2
    #   mkdocs-material
    #   mkdocs-mermaid2-plugin
    #   mkdocs-monorepo-plugin
    #   mkdocs-redirects
    #   mkdocs-section-index
    #   mkdocstrings
mkdocstrings==0.15.0
    # via -r requirements.docs.in
nltk==3.6.1
nltk==3.6.2
    # via lunr
pygments==2.8.1
pygments==2.9.0
    # via mkdocs-material
pykwalify==1.8.0
    # via -r requirements.docs.in
@@ -131,12 +135,13 @@ ruamel.yaml.clib==0.2.2
    # via ruamel.yaml
ruamel.yaml==0.17.4
    # via pykwalify
six==1.15.0
six==1.16.0
    # via
    #   astunparse
    #   jsbeautifier
    #   livereload
    #   lunr
    #   mkdocs-redirects
    #   python-dateutil
smmap==4.0.0
    # via gitdb
@@ -158,3 +163,4 @@ wheel==0.36.2
# The following packages are considered to be unsafe in a requirements file:
# setuptools
### END MKDOCS TEMPLATE ###
Original line number Diff line number Diff line
@@ -100,6 +100,7 @@ def add_internal_to_nav(
    """
    if nav_parent:
        for i_nav in nav:
            # "nav_entry" is a key of current parsed `nav`
            if nav_parent[0] in i_nav:
                for i_key in i_nav:
                    add_internal_to_nav(
@@ -109,6 +110,16 @@ def add_internal_to_nav(
                        repo_parent,
                        nav_parent[1:],
                    )
            # "nav_entry" is a subkey of current parsed `nav`
            elif nav_parent[0] in yaml.dump(i_nav):
                for i_key in i_nav:
                    add_internal_to_nav(
                        env,
                        i_nav[i_key],
                        repo_dict,
                        repo_parent,
                        nav_parent[0:],
                    )
    else:
        mkdocs_path = env.project_dir
        for i_parent in repo_parent:
@@ -153,6 +164,14 @@ def add_external_to_nav(
                        repo_parent,
                        nav_parent[1:],
                    )
    elif repo_dict["online_url"].startswith("/"):
        nav.append(
            {
                repo_dict["nav_entry"]: repo_dict["online_url"].replace(
                    "/", "../", 1
                )
            }
        )
    else:
        nav.append({repo_dict["nav_entry"]: repo_dict["online_url"]})

@@ -225,12 +244,14 @@ def update_nav(
            nav_parent.append(repo_dict["nav_entry"])
        elif i_key == "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_internal_to_nav(
                    env, env.conf["nav"], i_repo, repo_parent, nav_parent
                )
        elif i_key == "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_external_to_nav(
                    env, env.conf["nav"], i_repo, repo_parent, nav_parent
@@ -402,9 +423,7 @@ def set_copyright(env: dict, git_repo: git.Repo) -> None:
        curr_year = time.strftime("%Y", time.localtime())

        if first_year == curr_year:
            env.variables[
                "date_copyright"
            ] = f"Copyright &copy; {curr_year}"
            env.variables["date_copyright"] = f"Copyright &copy; {curr_year}"
        else:
            env.variables[
                "date_copyright"
@@ -415,7 +434,6 @@ def set_copyright(env: dict, git_repo: git.Repo) -> None:
        ] = f"{env.variables['date_copyright']} {env.variables['copyright']}"



def set_repo_name(env: dict, repo_slug: str) -> None:
    """Update content of the `repo_name` key in `env.conf`.

@@ -557,7 +575,7 @@ def set_config(env: dict) -> None:

    if "subrepo" in env.variables:
        if (
            env.variables["internal_subdoc"]
            not env.variables["internal_subdoc"]
            and "monorepo" in env.conf["plugins"]
        ):
            env.conf["plugins"].pop("monorepo")
@@ -678,7 +696,7 @@ def update_subrepo_info(
                f"{INFO_CLR}INFO [macros] - Pulling repo {i_repo['name']}{RESET_CLR}"
            )
            git_subrepo = git.Repo(subrepo_root)
            git_subrepo.remotes.origin.pull()
            git_subrepo.remotes.origin.pull('master')
        else:
            print(
                f"{INFO_CLR}INFO [macros] - Cloning repo {i_repo['name']}{RESET_CLR}"
@@ -822,21 +840,26 @@ def update_version(env: dict) -> None:
    mike_version = list()
    last_major = -1
    last_minor = -1
    last_patch = -1
    last_patch = str(-1)
    for i_tag in git_repo.tags:
        i_tag = yaml.dump(i_tag.path)
        i_tag = re.sub(".*v", "", i_tag).split(".")
        major = int(i_tag[0])
        minor = int(i_tag[1])
        patch = int(i_tag[2])
        patch = str()
        for i_remain_tag in i_tag[2:]:
            if i_remain_tag and i_remain_tag not in ("", "\n"):
                i_remain_tag = i_remain_tag.replace("\n", "")
                if not patch:
                    patch = f"{i_remain_tag}"
                else:
                    patch = f"{patch}.{i_remain_tag}"
        if major > last_major:
            if last_major >= 0:
                mike_version.append(
                    {
                        "version": "{}.{}".format(last_major, last_minor),
                        "title": "{}.{}.{}".format(
                            last_major, last_minor, last_patch
                        ),
                        "version": f"{last_major}.{last_minor}",
                        "title": f"{last_major}.{last_minor}.{last_patch}",
                        "aliases": [],
                    }
                )
@@ -846,21 +869,20 @@ def update_version(env: dict) -> None:
            if last_minor >= 0:
                mike_version.append(
                    {
                        "version": "{}.{}".format(last_major, last_minor),
                        "title": "{}.{}.{}".format(
                            last_major, last_minor, last_patch
                        ),
                        "version": f"{last_major}.{last_minor}",
                        "title": f"{last_major}.{last_minor}.{last_patch}",
                        "aliases": [],
                    }
                )
            last_minor = minor
            last_patch = -1
            last_patch = str(-1)
        if patch > last_patch:
            last_patch = patch
            last_patch = str(patch)

    mike_version.append(
        {
            "version": "{}.{}".format(last_major, last_minor),
            "title": "{}.{}.{}".format(last_major, last_minor, last_patch),
            "version": f"{last_major}.{last_minor}",
            "title": f"{last_major}.{last_minor}.{last_patch}",
            "aliases": ["latest"],
        }
    )
@@ -914,9 +936,11 @@ def define_env(env: dict) -> None:
            var: Key in env.variables to return.

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

    @env.macro
    # pylint: disable=W0612
Original line number Diff line number Diff line
@@ -26,11 +26,13 @@ repo_name:

  # (OPTIONAL) Path, relative to `docs_dir` mkdocs config, to the logo of the
  # repo. If not specified, path will automatically be set to
  # `assets/img/meta/reop_name_logo.png`
  #logo: "assets/img/meta/repo_template_logo.png"
  # `assets/img/meta/repo_name_logo.png`
  #logo: "assets/img/meta/repo_name_logo.png"
  # Description of the repo, will be used to setup the mkdocs description.
  desc: >-
    Repo description with markdown support
    An explicit description to explain what my repo do. Can be a multiline
    description with **markdown** support such as
    [link](https://url.domain.tld) and more.

  # (OPTIONAL) If you plan to use `mkdocstring` plugins to render python
  # source code, you will need to provide the path where your source files
Original line number Diff line number Diff line
@@ -22,6 +22,10 @@ subrepo:
  #     - name: subrepo_1
  #       # SSH or HTTP link to the online subrepo_1
  #       git_url: git@domain.tld:namesapce/subrepo_1
  #       # Key `subpath` is a str pointing to the path in the subrepo where
  #       # there is a file `mkdocs.yaml` and folder `docs` if not the root
  #       # of the subrepo
  #       subpath: sub/dir/
  #   # List of subdirectory from `dir_name` which are repos with
  #   # mkdocs documentation which will be included in the documentation.
  #   external:
@@ -31,6 +35,10 @@ subrepo:
  #     - name: subrepo_2
  #       # SSH or HTTP link to the online subrepo_2
  #       git_url: git@domain.tld:namesapce/subrepo_2
  #       # Key `subpath` is a str pointing to the path in the subrepo where
  #       # there is a file `mkdocs.yaml` and folder `docs` if not the root
  #       # of the subrepo
  #       subpath: sub/dir/
  #   # Another sub dir_name which also old subrepos
  #   subdir_name:
  #     nav_entry: "Sub Nav Entry"
Original line number Diff line number Diff line
@@ -6,7 +6,7 @@
#
astunparse==1.6.3
    # via pytkdocs
babel==2.9.0
babel==2.9.1
    # via mkdocs-git-revision-date-localized-plugin
click==7.1.2
    # via
@@ -49,20 +49,20 @@ mkdocs-autorefs==0.1.1
    # via mkdocstrings
mkdocs-exclude==1.0.2
    # 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
mkdocs-macros-plugin==0.5.5
    # via -r requirements.docs.in
mkdocs-material-extensions==1.0.1
    # via mkdocs-material
mkdocs-material==7.1.1
mkdocs-material==7.1.4
    # via
    #   -r requirements.docs.in
    #   mkdocs-macros-plugin
    #   mkdocs-material-extensions
mkdocs-monorepo-plugin==0.4.14
    # via -r requirements.docs.in
mkdocs-section-index==0.2.3
mkdocs-section-index==0.3.0
    # via -r requirements.docs.in
mkdocs==1.1.2
    # via
@@ -77,9 +77,9 @@ mkdocs==1.1.2
    #   mkdocstrings
mkdocstrings==0.15.0
    # via -r requirements.docs.in
nltk==3.6.1
nltk==3.6.2
    # via lunr
pygments==2.8.1
pygments==2.9.0
    # via mkdocs-material
pykwalify==1.8.0
    # via -r requirements.docs.in
@@ -105,7 +105,7 @@ ruamel.yaml.clib==0.2.2
    # via ruamel.yaml
ruamel.yaml==0.17.4
    # via pykwalify
six==1.15.0
six==1.16.0
    # via
    #   astunparse
    #   livereload