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