From e51783799e91b2e882406cf105fd6f2972c9df30 Mon Sep 17 00:00:00 2001 From: deadc0de6 Date: Sat, 12 Sep 2020 14:35:59 +0200 Subject: [PATCH] doc fix nested list --- docs/config/config-variables.md | 12 +- docs/config/config.md | 204 +++++++++++++-------------- docs/config/ignore-pattern.md | 12 +- docs/config/usage-transformations.md | 22 +-- docs/index.md | 32 ++--- docs/installation.md | 16 +-- docs/template/templating.md | 10 +- docs/usage.md | 30 ++-- 8 files changed, 169 insertions(+), 169 deletions(-) diff --git a/docs/config/config-variables.md b/docs/config/config-variables.md index 12a1627..fc74cc8 100644 --- a/docs/config/config-variables.md +++ b/docs/config/config-variables.md @@ -1,10 +1,10 @@ # Config variables * [Config available variables](available-variables) - * [Variables entry](#variables-entry) - * [Profile variables](#profile-variables) - * [Config variables in templates](#config-variables-in-templates) - * [Interpreted variables entry](#interpreted-variables-entry) + * [Variables entry](#variables-entry) + * [Profile variables](#profile-variables) + * [Config variables in templates](#config-variables-in-templates) + * [Interpreted variables entry](#interpreted-variables-entry) --- @@ -22,7 +22,7 @@ parametrize following elements of the config: `actions` and `transformations` also support the use of variables but those are resolved when the action/transformation is executed -(see [Dynamic actions](config#dynamic-actions), +(see [Dynamic actions](config#dynamic-actions), [Dynamic transformations](config#dynamic-transformations) and [Templating](templating)). Following variables are available in the config files: @@ -123,4 +123,4 @@ variables: dfl_config: "profile_default.yaml" ``` -They have the same properties as [Variables](#variables-entry). \ No newline at end of file +They have the same properties as [Variables](#variables-entry). diff --git a/docs/config/config.md b/docs/config/config.md index 8aa0617..c35be1d 100644 --- a/docs/config/config.md +++ b/docs/config/config.md @@ -5,22 +5,22 @@ The config file used by dotdrop is * [Location](#location) * [Format](#format) - * [Actions](#actions) - * [Transformations](#transformations) - * [Variables](#variables) - * [Interpreted variables](#interpreted-variables) + * [Actions](#actions) + * [Transformations](#transformations) + * [Variables](#variables) + * [Interpreted variables](#interpreted-variables) * Config details on - * [Symlinking dotfiles](#symlinking-dotfiles) - * [All dotfiles for a profile](#all-dotfiles-for-a-profile) - * [Include dotfiles from another profile](#include-dotfiles-from-another-profile) - * [Import profile dotfiles from file](#import-profile-dotfiles-from-file) - * [Import variables from file](#import-variables-from-file) - * [Import actions from file](#import-actions-from-file) - * [Import config files](#import-config-files) + * [Symlinking dotfiles](#symlinking-dotfiles) + * [All dotfiles for a profile](#all-dotfiles-for-a-profile) + * [Include dotfiles from another profile](#include-dotfiles-from-another-profile) + * [Import profile dotfiles from file](#import-profile-dotfiles-from-file) + * [Import variables from file](#import-variables-from-file) + * [Import actions from file](#import-actions-from-file) + * [Import config files](#import-config-files) * Dynamic elements - * [Dynamic dotfile paths](#dynamic-dotfile-paths) - * [Dynamic actions](#dynamic-actions) - * [Dynamic transformations](#dynamic-transformations) + * [Dynamic dotfile paths](#dynamic-dotfile-paths) + * [Dynamic actions](#dynamic-actions) + * [Dynamic transformations](#dynamic-transformations) --- @@ -45,77 +45,77 @@ Dotdrop config file uses [yaml](https://yaml.org/) syntax. Content Format: * **config** entry (mandatory): contains settings for the deployment - * `backup`: create a backup of the dotfile in case it differs from the - one that will be installed by dotdrop (default *true*) - * `banner`: display the banner (default *true*) - * `cmpignore`: list of patterns to ignore when comparing, apply to all dotfiles - (enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern)) - * `create`: create directory hierarchy when installing dotfiles if - it doesn't exist (default *true*) - * `default_actions`: list of action's keys to execute for all installed dotfile - (see [Use actions](usage-actions)) - * `diff_command`: the diff command to use for diffing files (default `diff -r -u {0} {1}`) - * `dotpath`: path to the directory containing the dotfiles to be managed (default `dotfiles`) - by dotdrop (absolute path or relative to the config file location) - * `filter_file`: list of paths to load templating filters from - (see [Templating available filters](templating#available-filters)) - * `func_file`: list of paths to load templating functions from - (see [Templating available methods](templating#available-methods)) - * `ignoreempty`: do not deploy template if empty (default *false*) - * `import_actions`: list of paths to load actions from - (absolute path or relative to the config file location, - see [Import actions from file](#import-actions-from-file)) - * `import_configs`: list of config file paths to be imported in - the current config (absolute path or relative to the current config file location, - see [Import config files](#import-config-files)) - * `import_variables`: list of paths to load variables from - (absolute path or relative to the config file location, - see [Import variables from file](#import-variables-from-file)) - * `instignore`: list of patterns to ignore when installing, apply to all dotfiles - (enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern)) - * `keepdot`: preserve leading dot when importing hidden file in the `dotpath` (default *false*) - * `link_dotfile_default`: set dotfile's `link` attribute to this value when undefined. - Possible values: *nolink*, *link*, *link_children* (default: *nolink*, - see [Symlinking dotfiles](#symlinking-dotfiles)) - * `link_on_import`: set dotfile's `link` attribute to this value when importing. - Possible values: *nolink*, *link*, *link_children* (default: *nolink*, - see [Symlinking dotfiles](#symlinking-dotfiles)) - * `longkey`: use long keys for dotfiles when importing (default *false*, - see [Import dotfiles](usage#import-dotfiles)) - * `minversion`: (*for internal use, do not modify*) provides the minimal dotdrop version to use - * `showdiff`: on install show a diff before asking to overwrite (see `--showdiff`) (default *false*) - * `upignore`: list of patterns to ignore when updating, apply to all dotfiles - (enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern)) - * `workdir`: path to the directory where templates are installed before being symlinked - when using `link:link` or `link:link_children` - (absolute path or relative to the config file location, defaults to *~/.config/dotdrop*) - * DEPRECATED `link_by_default`: when importing a dotfile set `link` to that value per default (default *false*) + * `backup`: create a backup of the dotfile in case it differs from the + one that will be installed by dotdrop (default *true*) + * `banner`: display the banner (default *true*) + * `cmpignore`: list of patterns to ignore when comparing, apply to all dotfiles + (enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern)) + * `create`: create directory hierarchy when installing dotfiles if + it doesn't exist (default *true*) + * `default_actions`: list of action's keys to execute for all installed dotfile + (see [Use actions](usage-actions)) + * `diff_command`: the diff command to use for diffing files (default `diff -r -u {0} {1}`) + * `dotpath`: path to the directory containing the dotfiles to be managed (default `dotfiles`) + by dotdrop (absolute path or relative to the config file location) + * `filter_file`: list of paths to load templating filters from + (see [Templating available filters](templating#available-filters)) + * `func_file`: list of paths to load templating functions from + (see [Templating available methods](templating#available-methods)) + * `ignoreempty`: do not deploy template if empty (default *false*) + * `import_actions`: list of paths to load actions from + (absolute path or relative to the config file location, + see [Import actions from file](#import-actions-from-file)) + * `import_configs`: list of config file paths to be imported in + the current config (absolute path or relative to the current config file location, + see [Import config files](#import-config-files)) + * `import_variables`: list of paths to load variables from + (absolute path or relative to the config file location, + see [Import variables from file](#import-variables-from-file)) + * `instignore`: list of patterns to ignore when installing, apply to all dotfiles + (enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern)) + * `keepdot`: preserve leading dot when importing hidden file in the `dotpath` (default *false*) + * `link_dotfile_default`: set dotfile's `link` attribute to this value when undefined. + Possible values: *nolink*, *link*, *link_children* (default: *nolink*, + see [Symlinking dotfiles](#symlinking-dotfiles)) + * `link_on_import`: set dotfile's `link` attribute to this value when importing. + Possible values: *nolink*, *link*, *link_children* (default: *nolink*, + see [Symlinking dotfiles](#symlinking-dotfiles)) + * `longkey`: use long keys for dotfiles when importing (default *false*, + see [Import dotfiles](usage#import-dotfiles)) + * `minversion`: (*for internal use, do not modify*) provides the minimal dotdrop version to use + * `showdiff`: on install show a diff before asking to overwrite (see `--showdiff`) (default *false*) + * `upignore`: list of patterns to ignore when updating, apply to all dotfiles + (enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern)) + * `workdir`: path to the directory where templates are installed before being symlinked + when using `link:link` or `link:link_children` + (absolute path or relative to the config file location, defaults to *~/.config/dotdrop*) + * DEPRECATED `link_by_default`: when importing a dotfile set `link` to that value per default (default *false*) * **dotfiles** entry (mandatory): a list of dotfiles - * `dst`: where this dotfile needs to be deployed - (dotfile with empty `dst` are ignored and considered installed, - can use `variables` and `dynvariables`, make sure to quote) - * `src`: dotfile path within the `dotpath` - (dotfile with empty `src` are ignored and considered installed, - can use `variables` and `dynvariables`, make sure to quote) - * `link`: define how this dotfile is installed. - Possible values: *nolink*, *link*, *link_children* (default: `link_dotfile_default`, - see [Symlinking dotfiles](#symlinking-dotfiles)) - * `actions`: list of action keys that need to be defined in the **actions** entry below - (see [Use actions](usage-actions)) - * `cmpignore`: list of patterns to ignore when comparing (enclose in quotes when using wildcards, - see [ignore patterns](ignore-pattern)) - * `ignoreempty`: if true empty template will not be deployed (defaults to the value of `ignoreempty` above) - * `instignore`: list of patterns to ignore when installing (enclose in quotes when using wildcards, - see [ignore patterns](ignore-pattern)) - * `trans_read`: transformation key to apply when installing this dotfile - (must be defined in the **trans_read** entry below, see [Use transformations](usage-transformations)) - * `trans_write`: transformation key to apply when updating this dotfile - (must be defined in the **trans_write** entry below, see [Use transformations](usage-transformations)) - * `upignore`: list of patterns to ignore when updating (enclose in quotes when using wildcards, - see [ignore patterns](ignore-pattern)) - * DEPRECATED `link_children`: replaced by `link: link_children` - * DEPRECATED `trans`: replaced by `trans_read` + * `dst`: where this dotfile needs to be deployed + (dotfile with empty `dst` are ignored and considered installed, + can use `variables` and `dynvariables`, make sure to quote) + * `src`: dotfile path within the `dotpath` + (dotfile with empty `src` are ignored and considered installed, + can use `variables` and `dynvariables`, make sure to quote) + * `link`: define how this dotfile is installed. + Possible values: *nolink*, *link*, *link_children* (default: `link_dotfile_default`, + see [Symlinking dotfiles](#symlinking-dotfiles)) + * `actions`: list of action keys that need to be defined in the **actions** entry below + (see [Use actions](usage-actions)) + * `cmpignore`: list of patterns to ignore when comparing (enclose in quotes when using wildcards, + see [ignore patterns](ignore-pattern)) + * `ignoreempty`: if true empty template will not be deployed (defaults to the value of `ignoreempty` above) + * `instignore`: list of patterns to ignore when installing (enclose in quotes when using wildcards, + see [ignore patterns](ignore-pattern)) + * `trans_read`: transformation key to apply when installing this dotfile + (must be defined in the **trans_read** entry below, see [Use transformations](usage-transformations)) + * `trans_write`: transformation key to apply when updating this dotfile + (must be defined in the **trans_write** entry below, see [Use transformations](usage-transformations)) + * `upignore`: list of patterns to ignore when updating (enclose in quotes when using wildcards, + see [ignore patterns](ignore-pattern)) + * DEPRECATED `link_children`: replaced by `link: link_children` + * DEPRECATED `trans`: replaced by `trans_read` ```yaml : @@ -138,18 +138,18 @@ Content Format: * **profiles** entry (mandatory): a list of profiles with the different dotfiles that need to be managed - * `dotfiles`: the dotfiles associated to this profile - * `import`: list of paths containing dotfiles keys for this profile - (absolute path or relative to the config file location, - see [Import profile dotfiles from file](#import-profile-dotfiles-from-file)). - * `include`: include all elements (dotfiles, actions, (dyn)variables, etc) from another profile - (see [Include dotfiles from another profile](#include-dotfiles-from-another-profile)) - * `variables`: profile specific variables - (see [Variables](#variables)) - * `dynvariables`: profile specific interpreted variables - (see [Interpreted variables](#interpreted-variables)) - * `actions`: list of action keys that need to be defined in the **actions** entry below - (see [Use actions](usage-actions)) + * `dotfiles`: the dotfiles associated to this profile + * `import`: list of paths containing dotfiles keys for this profile + (absolute path or relative to the config file location, + see [Import profile dotfiles from file](#import-profile-dotfiles-from-file)). + * `include`: include all elements (dotfiles, actions, (dyn)variables, etc) from another profile + (see [Include dotfiles from another profile](#include-dotfiles-from-another-profile)) + * `variables`: profile specific variables + (see [Variables](#variables)) + * `dynvariables`: profile specific interpreted variables + (see [Interpreted variables](#interpreted-variables)) + * `actions`: list of action keys that need to be defined in the **actions** entry below + (see [Use actions](usage-actions)) ```yaml : @@ -422,11 +422,11 @@ import_actions: Entire config files can be imported. This means making the following available from the imported config file in the original config file: -- dotfiles -- profiles -- actions -- read/write transformations -- variables/dynvariables +* dotfiles +* profiles +* actions +* read/write transformations +* variables/dynvariables Paths to import can be absolute or relative to the importing config file location. @@ -552,7 +552,7 @@ Make sure to quote the actions using variables. # Dynamic transformations -As for [dynamic actions](#dynamic-actions), transformations support +As for [dynamic actions](#dynamic-actions), transformations support the use of variables ([variables and dynvariables](config-variables) and [template variables](templating#template-variables)). @@ -578,4 +578,4 @@ dotfiles: src: def trans_read: r_echo_var trans_write: w_echo_var -``` \ No newline at end of file +``` diff --git a/docs/config/ignore-pattern.md b/docs/config/ignore-pattern.md index 788dd26..31a83da 100644 --- a/docs/config/ignore-pattern.md +++ b/docs/config/ignore-pattern.md @@ -9,13 +9,13 @@ It is possible to ignore specific patterns when using dotdrop. For example for ` files don't need to appear in the output. * for [install](usage#install-dotfiles) - * using `instignore` in [the config file](config) + * using `instignore` in [the config file](config) * for [compare](usage#compare-dotfiles) - * using `cmpignore` in [the config file](config) - * using the command line switch `-i --ignore` + * using `cmpignore` in [the config file](config) + * using the command line switch `-i --ignore` * for [update](usage#update-dotfiles) - * using `upignore` in [the config file](config) - * using the command line switch `-i --ignore` + * using `upignore` in [the config file](config) + * using the command line switch `-i --ignore` The ignore pattern must follow Unix shell-style wildcards like for example `*/path/to/file`. Make sure to quote those when using wildcards in the config file. @@ -61,4 +61,4 @@ dotfiles: dst: ~/.config/some_directory upignore: - '*sub_directory_to_ignore' -``` \ No newline at end of file +``` diff --git a/docs/config/usage-transformations.md b/docs/config/usage-transformations.md index f2ce828..0fdc4fd 100644 --- a/docs/config/usage-transformations.md +++ b/docs/config/usage-transformations.md @@ -5,24 +5,24 @@ --- **Note**: any transformation with a key starting with an underscore (`_`) won't be shown in output. -This can be useful when working with sensitive data containing passwords for example. +This can be useful when working with sensitive data containing passwords for example. # Use transformations There are two types of transformations available: * **read transformations**: used to transform dotfiles before they are installed ([Config](config) key `trans_read`) - * Used for commands `install` and `compare` - * They have two arguments: - * **{0}** will be replaced with the dotfile to process - * **{1}** will be replaced with a temporary file to store the result of the transformation - * Happens **before** the dotfile is templated with jinja2 (see [templating](templating)) + * Used for commands `install` and `compare` + * They have two arguments: + * **{0}** will be replaced with the dotfile to process + * **{1}** will be replaced with a temporary file to store the result of the transformation + * Happens **before** the dotfile is templated with jinja2 (see [templating](templating)) * **write transformations**: used to transform files before updating a dotfile ([Config](config) key `trans_write`) - * Used for command `update` - * They have two arguments: - * **{0}** will be replaced with the file path to update the dotfile with - * **{1}** will be replaced with a temporary file to store the result of the transformation + * Used for command `update` + * They have two arguments: + * **{0}** will be replaced with the file path to update the dotfile with + * **{1}** will be replaced with a temporary file to store the result of the transformation A typical use-case for transformations is when dotfiles need to be stored encrypted or compressed. For more see below [examples](#examples). @@ -52,7 +52,7 @@ will result in `abc; f_abc; p1; lastarg` # Examples -See +See * [Store compressed directories](store-compressed-directories) * [Sensitive dotfiles](sensitive-dotfiles) diff --git a/docs/index.md b/docs/index.md index e3f6969..3e7b629 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,22 +14,22 @@ For more examples of config file, [search github](https://github.com/search?q=fi # Wiki pages * Documentation - * [Installation](installation) - * [Usage](usage) - * [Config file format](config) - * [Templating](templating) + * [Installation](installation) + * [Usage](usage) + * [Config file format](config) + * [Templating](templating) * How To - * [Use actions](usage-actions) - * [Use transformations](usage-transformations) - * [Store secrets](sensitive-dotfiles) - * [Symlink dotfiles](symlinked-dotfiles) - * [Store compressed directories](store-compressed-directories) - * [Merge files when installing](merge-files-when-installing) - * [Append to a dotfile](append) - * [Manage system/global config files](global-config-files) - * [Handle special chars](special-chars) - * [Share content across dotfiles](sharing-content) - * [Ignore patterns](ignore-pattern) - * [Create special files](create-special-files) + * [Use actions](usage-actions) + * [Use transformations](usage-transformations) + * [Store secrets](sensitive-dotfiles) + * [Symlink dotfiles](symlinked-dotfiles) + * [Store compressed directories](store-compressed-directories) + * [Merge files when installing](merge-files-when-installing) + * [Append to a dotfile](append) + * [Manage system/global config files](global-config-files) + * [Handle special chars](special-chars) + * [Share content across dotfiles](sharing-content) + * [Ignore patterns](ignore-pattern) + * [Create special files](create-special-files) * [Related projects](related-projects) * [Troubleshooting](troubleshooting) diff --git a/docs/installation.md b/docs/installation.md index 3f13e5f..2738f4a 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -10,12 +10,12 @@ In that case, the virtualenv environment might need to be loaded before any atte Installation instructions * Installation - * [Install as a submodule](#as-a-submodule) - * [Install as a submodule in a virtualenv](#as-a-submodule-in-a-virtualenv) - * [Install with pypi](#with-pypi) - * [Install with pypi in a virtualenv](#with-pypi-in-a-virtualenv) - * [Aur packages](#aur-packages) - * [Snap package](#snap-package) + * [Install as a submodule](#as-a-submodule) + * [Install as a submodule in a virtualenv](#as-a-submodule-in-a-virtualenv) + * [Install with pypi](#with-pypi) + * [Install with pypi in a virtualenv](#with-pypi-in-a-virtualenv) + * [Aur packages](#aur-packages) + * [Snap package](#snap-package) * [Setup your repository](#setup-your-repository) * [Shell completion](#shell-completion) * [Dependencies](dependencies) @@ -128,7 +128,7 @@ Then follow the [doc to setup your repository](#setup-your-repository). # Setup your repository Either create a repository on your prefered platform and clone it or create one locally. -This repository will contain two main elements, dotdrop's config file (`config.yaml`) +This repository will contain two main elements, dotdrop's config file (`config.yaml`) and a directory containing all your dotfiles managed by dotdrop. ```bash ## clone your repository (my-dotfiles) @@ -169,4 +169,4 @@ Finally start using dotdrop with `dotdrop --help`. See the [usage doc](https://g # Shell completion -Completion scripts exist for `bash`, `zsh` and `fish`, see [the related doc](completion/README.md). \ No newline at end of file +Completion scripts exist for `bash`, `zsh` and `fish`, see [the related doc](completion/README.md). diff --git a/docs/template/templating.md b/docs/template/templating.md index b932a6e..1178493 100644 --- a/docs/template/templating.md +++ b/docs/template/templating.md @@ -6,9 +6,9 @@ or the below sections for more information on how to template your dotfiles. * [Delimiters](#delimiters) * [Template variables](#template-variables) - * [Dotfile variables](#dotfile-variables) - * [Environment variables](#environment-variables) - * [Dotdrop header](#dotdrop-header) + * [Dotfile variables](#dotfile-variables) + * [Environment variables](#environment-variables) + * [Dotdrop header](#dotdrop-header) * [Available methods](#available-methods) * [Available filters](#available-filters) * [Import macros](#import-macros) @@ -114,7 +114,7 @@ The header can be automatically added with: Properly commenting the header in templates is the responsibility of the user as [jinja2](http://jinja.pocoo.org/) has no way of knowing what is the proper char(s) used for comments. -Either prepend the directive with the commenting char(s) used in the dotfile +Either prepend the directive with the commenting char(s) used in the dotfile (for example `# {{@@ header() @@}}`) or provide it as an argument `{{@@ header('# ') @@}}`. The result is equivalent. @@ -197,7 +197,7 @@ dotfile content {{@@ "13" | myfilter() @@}} ``` -For more information on how to create filters, +For more information on how to create filters, see [jinja2 official doc](https://jinja.palletsprojects.com/en/2.10.x/api/#writing-filters). # Import macros diff --git a/docs/usage.md b/docs/usage.md index 051c69c..e3937f7 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -4,16 +4,16 @@ Run `dotdrop --help` to see all available options. * [Basic use](#basic-use) * Commands: - * [Install dotfiles](#install-dotfiles) - * [Compare dotfiles](#compare-dotfiles) - * [Import dotfiles](#import-dotfiles) - * [List profiles](#list-profiles) - * [List dotfiles](#list-dotfiles) - * [Update dotfiles](#update-dotfiles) - * [Remove dotfiles](#remove-dotfiles) + * [Install dotfiles](#install-dotfiles) + * [Compare dotfiles](#compare-dotfiles) + * [Import dotfiles](#import-dotfiles) + * [List profiles](#list-profiles) + * [List dotfiles](#list-dotfiles) + * [Update dotfiles](#update-dotfiles) + * [Remove dotfiles](#remove-dotfiles) * Uses - * [Use actions](usage-actions) - * [Use transformations](usage-transformations) + * [Use actions](usage-actions) + * [Use transformations](usage-transformations) * [Update dotdrop](#update-dotdrop) * [Environment variables](#environment-variables) * [User tricks](#user-tricks) @@ -85,18 +85,18 @@ with the option `longkey` (per default to *false*). Two formats are available: - * *short format* (default): take the shortest unique path - * *long format*: take the full path +* *short format* (default): take the shortest unique path +* *long format*: take the full path For example `~/.config/awesome/rc.lua` gives - * `f_rc.lua` in the short format - * `f_config_awesome_rc.lua` in the long format +* `f_rc.lua` in the short format +* `f_config_awesome_rc.lua` in the long format Importing `~/.mutt/colors` and then `~/.vim/colors` will result in - * `d_colors` and `d_vim_colors` in the short format - * `d_mutt_colors` and `d_vim_colors` in the long format +* `d_colors` and `d_vim_colors` in the short format +* `d_mutt_colors` and `d_vim_colors` in the long format Dotfile can be imported as a different file with the use of the command line switch `--as`. It is however recommended