diff --git a/README.md b/README.md
index e7190b2c20644a76255fb8afaa35775ff1e3641c..f6b2918e2bf9115c520d09f68aa3d87c80dff10e 100644
--- a/README.md
+++ b/README.md
@@ -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
diff --git a/docs/_data/extra.yaml b/docs/_data/extra.yaml
index 7cb8bd56bff0e58c81348682cc1b4960e5439491..adb6853397af25554b1c5997844129ea20fe0820 100644
--- a/docs/_data/extra.yaml
+++ b/docs/_data/extra.yaml
@@ -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"
diff --git a/docs/_data/plugins.py b/docs/_data/plugins.py
index cbac0510eaaef2f22dcce4593f6c701b341d8066..d47f6ebb412742d56dc34d39bd2b4f7713e21e0b 100644
--- a/docs/_data/plugins.py
+++ b/docs/_data/plugins.py
@@ -153,6 +153,10 @@ def add_external_to_nav(
repo_parent,
nav_parent[1:],
)
+ elif repo_dict["online_url"].startswith('/'):
+ nav.append({
+ repo_dict["nav_entry"]: repo_dict["online_url"].replace('/','../',1)
+ })
else:
nav.append({repo_dict["nav_entry"]: repo_dict["online_url"]})
@@ -833,10 +837,8 @@ def update_version(env: dict) -> None:
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,10 +848,8 @@ 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": [],
}
)
@@ -859,8 +859,8 @@ def update_version(env: dict) -> None:
last_patch = 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 +914,11 @@ def define_env(env: dict) -> None:
var: Key in env.variables to return.
Returns:
- The value of `env.variables[var]`.
+ The value of `env.variables[var]` if it exists, else return None.
"""
- return env.variables[var]
+ if var in env.variables:
+ return env.variables[var]
+ return None
@env.macro
# pylint: disable=W0612
diff --git a/docs/_data/template/repo.tpl.yaml b/docs/_data/template/repo.tpl.yaml
index 8fb19b07957b60bfcd8e20aa45b32f96271618ce..900e5c8fcbe87feda0168e5c18d2772b38ed2de0 100644
--- a/docs/_data/template/repo.tpl.yaml
+++ b/docs/_data/template/repo.tpl.yaml
@@ -1,3 +1,4 @@
+
### 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 ###
+
diff --git a/docs/_data/template/subrepo.tpl.yaml b/docs/_data/template/subrepo.tpl.yaml
index 07ca0f40be28fa4711ace0eb6a5c95aace2b4f0d..bd0ff061b65b6fc3a55ddfc5b52a62ef7a4787df 100644
--- a/docs/_data/template/subrepo.tpl.yaml
+++ b/docs/_data/template/subrepo.tpl.yaml
@@ -1,3 +1,4 @@
+
### 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 ###
+
diff --git a/docs/about/contributing.md b/docs/about/contributing.md
index 50e515e47b16f24be2abd0fe2a017621e19afeb7..a71d0fbfab70468f99593fcba53c5d761dcb49b2 100644
--- a/docs/about/contributing.md
+++ b/docs/about/contributing.md
@@ -1,5 +1,6 @@
{% 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 -->
+
diff --git a/docs/about/release_notes.md b/docs/about/release_notes.md
index 40e0ea3667a6c0f03b42359f272088894f497d22..6e3c130792fcc8c30afb0259c8aaae2ac003bd67 100644
--- a/docs/about/release_notes.md
+++ b/docs/about/release_notes.md
@@ -10,6 +10,18 @@ Modified content will be overwritten when updating
## 🔖 v1.0
+### 🔖 v1.0.3 <small>(13/05/2021)</small>
+
+- 📠Update documentation content.
+- 🔧 Update extra content through yaml `_data·` files
+ - Add new content
+ - Add documentation in template files
+- ✨ Improve `plugins.py` behaviour
+ - Convert `.format()` string into `f""` string
+ - Fix configuration management
+- ⬆📌 Upgrade pinned python dependencies
+
+
### 🔖 v1.0.2 <small>(29/04/2021)</small>
- ðŸ“📄 Update copyright in license content
diff --git a/docs/personal_template/create.md b/docs/personal_template/create.md
index 89941a46b7e5895ef8bb49679db45ece6aabb57e..19540cbcbc9e24ca079f67a8cfd766c5add9aa79 100644
--- a/docs/personal_template/create.md
+++ b/docs/personal_template/create.md
@@ -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
diff --git a/docs/personal_template/example.md b/docs/personal_template/example.md
index a56a7200ceab903dba26bc0dd08807aa8c4ffb2d..7f1b614dad8465ac22b2bd8604800379304313f1 100644
--- a/docs/personal_template/example.md
+++ b/docs/personal_template/example.md
@@ -1,7 +1,7 @@
{% 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]
diff --git a/docs/personal_template/index.md b/docs/personal_template/index.md
index 40b4591ba8b273a673eefa198def969071e89239..67560063d187cf98bed8aa151356e251134355b1 100644
--- a/docs/personal_template/index.md
+++ b/docs/personal_template/index.md
@@ -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:
diff --git a/docs/references/preview.md b/docs/references/preview.md
index ce89f81459ee0fcce40322f151bc55a706d4675a..11d114ed91d74a91355c10a00a19b9de3f478458 100644
--- a/docs/references/preview.md
+++ b/docs/references/preview.md
@@ -10,36 +10,31 @@ Setup a temporary documentation folder to preview the rendering of the template
This script will build the final list of folder that will be installed in
the folder that will host the documenation and render a preview of such
-basic documenation based from template.
+basic documentation based from template.
This will be done by creating symlinks from `templates` and `user_config`
folders into `preview` folder.
Available options are:
- `-c,--clean` : Remove every existing symlinks before rendering the
- preview.
+ * `-c,--clean` : Remove every existing symlinks before rendering the
+ preview.
- `-r,--very-clean` : Remove every existing symlinks without rendering the
- preview.
+ * `-r,--very-clean` : Remove every existing symlinks without rendering the
+ preview.
- `-h,--help` : Print this help.
+ * `-h,--help` : Print this help.
## main()
- **Setup folder to be able to use directory environment mechanism**
-
- Check if git is installed. Then check that folder is not already using
- mkdocs documentation.
-
- If directory already set to use directory environment, then check if user
- explicitly tell to upgrade and upgrade, otherwise, print a warning and exit.
-
- If directory not already set to use directory environment, clone
- user provided repo to a temporary folder, copy relevant scripts, files and
- folders to initiliaze a documentation rendered using mkdocs.
+ **Setup preview folder to be able to see the rendering of the documentation template.**
+
+ Build the list of the file that will be installed if using the mkdocs
+ documentation template, make a symlinks of all these files into `preview`
+ folder and, depending on the options provided, render the documentation
+ preview.
**Globals**
@@ -54,9 +49,9 @@ Available options are:
| Arguments | Description |
| :-------- | :---------- |
- | `-u,--upgrade` | -u,--upgrade |
- | `-r,--repo-url REPO_URL` | -r,--repo-url REPO_URL |
- | `-s,--subrepo` | -s,--subrepo |
+ | `-c,--clean` | Remove every existing symlinks before rendering the preview. |
+ | `-r,--very-clean` | Remove every existing symlinks without rendering the preview. |
+ | `-h,--help` | Print this help. |
**Output**
@@ -64,13 +59,13 @@ Available options are:
**Returns**
- - 0 if directory is correctly configure to start writing documentation
- - 1 if something when wrong during the setup of documentation
+ - 0, if rendering of the preview documentation went right.
+ - 1, if rendering of the preview documentation went wrong.
### manpage()
-> **Extract the script documentation from header and print it on stdout**
->
+> **Extract the script documentation from header and print it on stdout.**
+>
> Simply extract the docstring from the header of the script, format it with
> some output enhancement (such as bold) and print it to stdout.
>
@@ -86,16 +81,16 @@ Available options are:
### mkdocs_log()
-> **Print debug message in colors depending on message severity on stderr**
->
+> **Print debug message in colors depending on message severity on stderr.**
+>
> Echo colored log depending on user provided message severity. Message
> severity are associated to following color output:
->
+>
> - `DEBUG` print in the fifth colors of the terminal (usually magenta)
> - `INFO` print in the second colors of the terminal (usually green)
> - `WARNING` print in the third colors of the terminal (usually yellow)
> - `ERROR` print in the third colors of the terminal (usually red)
->
+>
> If no message severity is provided, severity will automatically be set to
> INFO.
>
@@ -119,7 +114,7 @@ Available options are:
### build_file_list()
> **Recursively build a list of file from provided folder**
->
+>
> Recursively build a list of file from provided folder and store such list
> in a temporary bash array that must be set in parent method.
>
@@ -128,18 +123,19 @@ Available options are:
>
> | Arguments | Description |
> | :-------- | :---------- |
-> | `$1, string, absolute path to the folder which will be parsed` | $1, string, absolute path to the folder which will be parsed |
+> | `$1` | string, absolute path to the folder which will be parsed |
>
>
### build_final_file_list()
-> **Replate templates file by user configured files**
->
+> **Build the merged list from `templates` and `user_config` folder.**
+>
> If there is the same file in `user_config` and `templates` folder, then
> replace the file to be installed from `templates` by the one in
> `user_config`. Finally, add remaining `user_config` files not in
-> `templates` to the list of files to install or upgrade in a bash array.
+> `templates` to the list of files to install or upgrade in a bash array set
+> in parent method.
>
> **Globals**
>
@@ -150,7 +146,8 @@ Available options are:
### clean_preview()
> **Recursively clean the preview folder by removing all symlinks**
->
+>
+> Simply remove recursively all symlinks from folder `preview`.
>
> **Globals**
>
@@ -165,11 +162,11 @@ Available options are:
### setup_mkdocs()
-> **Recursively install base folder and script to write mkdocs documentation.**
->
-> Build the list of files and folders, recursively copy all files to
-> their right location from the temporary clone repo to the folder which
-> will host the mkdocs documentation.
+> **Recursively install base folder and script to render a preview of the documentation template.**
+>
+> Build the list of files and folders, recursively create a symlink of all
+> files to their right location from the temporary clone repo to the folder
+> `preview`.
>
> **Globals**
>
diff --git a/docs/usage/configure.md b/docs/usage/configure.md
index 81d79e973bc68efe54070ab819af2036d49d669d..a47e6a6a547fe06b4c452ec247a9a65e7a8a638f 100644
--- a/docs/usage/configure.md
+++ b/docs/usage/configure.md
@@ -1,13 +1,13 @@
# 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"
diff --git a/docs/usage/setup.md b/docs/usage/setup.md
index 7baf73d6e06e40f639c8147697f33fd3a2e19be1..bc3e61883c10cbbc63e6c529a6f7280b311e72f9 100644
--- a/docs/usage/setup.md
+++ b/docs/usage/setup.md
@@ -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
diff --git a/docs/usage/upgrade.md b/docs/usage/upgrade.md
index a8b07dab75c0ee64e9b7a94252973355cce97bc9..a712b7f5b89186099fdd734a7f886945195b3d34 100644
--- a/docs/usage/upgrade.md
+++ b/docs/usage/upgrade.md
@@ -1,8 +1,8 @@
{% 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
diff --git a/mkdocs.yml b/mkdocs.yml
index df41e3ef7399f752c1c60e60d69f591787df6187..19f3e777eb6a5e54863ab235ceaea662344aab08 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -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
diff --git a/requirements.dev.txt b/requirements.dev.txt
index c09aa98667b394e29dd441dedf3d1f772e99279c..e9f4d807a93508fc61298e39383f2c890d6d74f9 100644
--- a/requirements.dev.txt
+++ b/requirements.dev.txt
@@ -1,4 +1,3 @@
-
### 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 ###
-
diff --git a/requirements.docs.in b/requirements.docs.in
index 7063c281788b0a39ca63acdd8c64029d7d6b5dd3..0113e9bd119bbf02df8f41136233d57c69847e63 100644
--- a/requirements.docs.in
+++ b/requirements.docs.in
@@ -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 ###
diff --git a/requirements.docs.txt b/requirements.docs.txt
index c5d426116a81408bbbec53578d485392630c0070..07ab8e9885321b9bff4778eb2eb1371c805c5428 100644
--- a/requirements.docs.txt
+++ b/requirements.docs.txt
@@ -1,3 +1,4 @@
+
### 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 ###
+
diff --git a/templates/docs/_data/plugins.py b/templates/docs/_data/plugins.py
index cbac0510eaaef2f22dcce4593f6c701b341d8066..d47f6ebb412742d56dc34d39bd2b4f7713e21e0b 100644
--- a/templates/docs/_data/plugins.py
+++ b/templates/docs/_data/plugins.py
@@ -153,6 +153,10 @@ def add_external_to_nav(
repo_parent,
nav_parent[1:],
)
+ elif repo_dict["online_url"].startswith('/'):
+ nav.append({
+ repo_dict["nav_entry"]: repo_dict["online_url"].replace('/','../',1)
+ })
else:
nav.append({repo_dict["nav_entry"]: repo_dict["online_url"]})
@@ -833,10 +837,8 @@ def update_version(env: dict) -> None:
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,10 +848,8 @@ 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": [],
}
)
@@ -859,8 +859,8 @@ def update_version(env: dict) -> None:
last_patch = 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 +914,11 @@ def define_env(env: dict) -> None:
var: Key in env.variables to return.
Returns:
- The value of `env.variables[var]`.
+ The value of `env.variables[var]` if it exists, else return None.
"""
- return env.variables[var]
+ if var in env.variables:
+ return env.variables[var]
+ return None
@env.macro
# pylint: disable=W0612
diff --git a/templates/docs/_data/template/repo.tpl.yaml b/templates/docs/_data/template/repo.tpl.yaml
index e86ea591a9789ec0a7728e068c997aa9f079dc57..b4ce1913d8cfc508dcf71bb162a6ebfed3ed6e73 100644
--- a/templates/docs/_data/template/repo.tpl.yaml
+++ b/templates/docs/_data/template/repo.tpl.yaml
@@ -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
diff --git a/templates/docs/_data/template/subrepo.tpl.yaml b/templates/docs/_data/template/subrepo.tpl.yaml
index d23a85e17a4e7639e7b653ed7a806534431be4fb..a62c63239fba08640d5290dfafd91c27fd993493 100644
--- a/templates/docs/_data/template/subrepo.tpl.yaml
+++ b/templates/docs/_data/template/subrepo.tpl.yaml
@@ -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"
diff --git a/templates/requirements.docs.txt b/templates/requirements.docs.txt
index 570900a0594a752d255cd1a0316d156e5baed9ce..d4866865c924581d3988ee0cc05ec76a104f02a5 100644
--- a/templates/requirements.docs.txt
+++ b/templates/requirements.docs.txt
@@ -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