Review documentation content

Review documentation, mainly update some links and fix grammatical mistakes.

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

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"

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

docs/personal_template/example.md

 {% 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]

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:

docs/usage/configure.md

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

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

docs/usage/upgrade.md

 {% 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