From 2dc4b0b8685db78cfc9d506a00a58619984905d7 Mon Sep 17 00:00:00 2001 From: AnonymouX47 Date: Fri, 7 Apr 2023 17:30:27 +0100 Subject: [PATCH] docs: Link CLI option references - Change: Use the `option` role for all CLI option references. - Change: Update CLI help text markup stripping for CLI options. --- docs/source/cli.rst | 18 +++++++------ docs/source/concepts.rst | 32 +++++++++++++---------- docs/source/config.rst | 18 +++++++------ docs/source/faqs.rst | 5 ++-- docs/source/glossary.rst | 14 +++++----- docs/source/issues.rst | 2 +- docs/source/tui.rst | 4 +-- src/termvisage/parsers.py | 54 +++++++++++++++++++++++++++------------ 8 files changed, 89 insertions(+), 58 deletions(-) diff --git a/docs/source/cli.rst b/docs/source/cli.rst index a40b94a..d19ed45 100644 --- a/docs/source/cli.rst +++ b/docs/source/cli.rst @@ -29,9 +29,9 @@ Options and Arguments .. [#] See :ref:`render-styles`. .. [#] In CLI mode, only image sources are used, directory sources are skipped. - Animated images are displayed only when animation is disabled (with ``--no-anim``), - when there's only one image source or when using native animation of some render - styles. + Animated images are displayed only when animation is disabled (with + :option:`--no-anim `), when there's only one image source + or when using native animation of some render styles. .. [#] Frames will not be cached for any animation with more frames than this value. Memory usage depends on the frame count **per image**, not this maximum count. @@ -42,12 +42,13 @@ Options and Arguments .. [#] Width and height are in units of columns and lines repectively. By default (i.e if none of the sizing options is specified), the equivalent of - ``--original-size`` is used if not larger than the :term:`available size`, else - ``--fit``. + :option:`--original-size ` is used if not larger than + the :term:`available size`, else :option:`--fit `. .. [#] Any image having more pixels than the specified maximum will be: - - skipped, in CLI mode, if ``--max-pixels-cli`` is specified. + - skipped, in CLI mode, if :option:`--max-pixels-cli ` + is specified. - replaced, in TUI mode, with a placeholder when displayed but can still be explicitly made to display. @@ -67,12 +68,13 @@ Options and Arguments terminal's end but at the cost of image quality and color reproduction. - is useful for animations with high resolution and/or sparse color distribution. - only applies when an image is re-encoded and not read directly from file - (see ``--itnrff | --iterm2-no-read-from-file``). + (see :option:`--itnrff | --iterm2-no-read-from-file `). - can only be used for non-transparent images but the transparency status of some images can not be correctly determined in an efficient way at render time. Thus, to ensure the JPEG format is always used for re-encoded images, disable - transparency (``--no-alpha``) or set a background color (``-b | --alpha-bg``). + transparency (:option:`--no-alpha `) or set a background + color (:option:`-b | --alpha-bg `). .. [#] By default, image data is used directly from file when no image manipulation is required. Otherwise, it's re-encoded in PNG (or JPEG, if enabled) format. diff --git a/docs/source/concepts.rst b/docs/source/concepts.rst index d6022d8..cacbf5c 100644 --- a/docs/source/concepts.rst +++ b/docs/source/concepts.rst @@ -29,9 +29,9 @@ The viewer can be used in two modes: In this mode, images are directly printed to standard output. It is used when - * output is not a terminal (even if ``--tui`` is specified) + * output is not a terminal (even if :option:`--tui ` is specified) * there is only a single image source - * the ``--cli`` option is specified + * :option:`--cli ` is specified 2. **TUI mode** @@ -40,7 +40,7 @@ The viewer can be used in two modes: * there is at least one non-empty directory source * there are multiple image sources - * the ``--tui`` option is specified + * :option:`--tui ` is specified .. _render-styles: @@ -51,8 +51,8 @@ Render Styles See :term:`render style`. By default, the best style supported by the :term:`active terminal` is automatically detected. -A particular render style can be specified using :confval:`style` or the ``-S | --style`` -command-line option. +A particular render style can be specified using :confval:`style` or +:option:`-S | --style `. If the specified render style is: @@ -86,8 +86,8 @@ The available render styles are: with a density of two pixels per character cell. Using a render style not supported by the :term:`active terminal` is not allowed by -default. To force the usage of a style that is normally unsupported, add the -``--force-style`` flag. +default. To force the usage of a style that is normally unsupported, add +:option:`--force-style `. .. _cell-ratio: @@ -99,8 +99,9 @@ The :term:`cell ratio` is taken into consideration when setting image sizes for **text-based** render styles, in order to preserve the aspect ratio of images drawn to the terminal. -This value is determined by :confval:`cell ratio` OR either of the command-line options -``-C | --cell-ratio`` or ``--auto-cell-ratio``. +This value is determined by :confval:`cell ratio` OR either of +:option:`-C | --cell-ratio ` or +:option:`--auto-cell-ratio `. The command-line options are mutually exclusive and override the config option. By default (i.e without changing the config option value or specifying either @@ -145,10 +146,11 @@ Logging Logs are more detailed event reports meant for troubleshooting and debugging purporses. -Logs are written to a file on a local filesystem. The default log file is ``~/.termvisage/termvisage.log`` but a different file can be specified: +Logs are written to a file on a local filesystem. The default log file is +``~/.termvisage/termvisage.log`` but a different file can be specified: * for all sessions, using :confval:`log file` -* per session, using the ``-l | --log-file`` command-line option +* per session, using :option:`-l | --log-file ` A log entry has the following format: @@ -160,13 +162,17 @@ A log entry has the following format: * *date* and *time*: Current system date and time in the format ``%Y-%m-%d %H:%M:%S,``, where ```` is in milliseconds. * *process* and *thread*: The names of the python process and thread that produced the log record. - * Only present when the *logging level* is set to ``DEBUG`` (either by ``--debug`` or ``--log-level=DEBUG``). + * Only present when the *logging level* is set to ``DEBUG`` (either by + :option:`--debug ` or + :option:`--log-level=DEBUG `). * *level*: The level of the log entry, this indicates it's importance. * *module*: The package sub-module from which it originated. * *function*: The function from which it originated. - * Only present when running on **Python 3.8+** and *logging level* is set to ``DEBUG`` (either by ``--debug`` or ``--log-level=DEBUG``). + * Only present when running on **Python 3.8+** and *logging level* is set to ``DEBUG`` + (either by :option:`--debug ` or + :option:`--log-level=DEBUG `). * *message*: The actual report describing the event that occured. diff --git a/docs/source/config.rst b/docs/source/config.rst index f815aa6..6565c9a 100644 --- a/docs/source/config.rst +++ b/docs/source/config.rst @@ -22,16 +22,16 @@ If multiple config files are found (i.e in different locations), they're applied one another **in the order in which they were found**. Hence, a field present in the latter, if valid, will override the same field also present in the former. -An alternative config file can be specified per-session using the ``--config`` command-line -option. +An alternative config file can be specified per-session using +:option:`--config `. -To use the default configuration and not load any config file, use the ``--no-config`` -command-line option. +To use the default configuration and not load any config file, use +:option:`--no-config `. .. hint:: ``termvisage`` performs [quite] thorough validation on the values specified in a config file and reports any errors. To see information about how the errors are resolved - (if resolvable), use the ``-v | --verbose`` command-line option. + (if resolvable), use :option:`-v | --verbose `. `This `_ is a sample config file with all options and keybindings at their defaults. @@ -133,7 +133,8 @@ These are top-level fields whose values control various settings of the viewer. Any image having more pixels than the specified value will be: - * skipped, in CLI mode, if ``--max-pixels-cli`` is specified. + * skipped, in CLI mode, if :option:`--max-pixels-cli ` + is specified. * replaced, in TUI mode, with a placeholder when displayed but can still be forced to display or viewed externally. @@ -162,8 +163,9 @@ These are top-level fields whose values control various settings of the viewer. :valid: ``"auto"``, ``"block"``, ``"iterm2"``, ``"kitty"`` :default: ``"auto"`` - If set to any value other than ``"auto"`` and is not overriden by the ``-S | --style`` - command-line option, the style is used regardless of whether it's supported or not. + If set to any value other than ``"auto"`` and is not overriden by + :option:`-S | --style `, the style is used regardless of whether + it's supported or not. .. confval:: swap win size :synopsis: A workaround for some terminal emulators (e.g older VTE-based ones) that diff --git a/docs/source/faqs.rst b/docs/source/faqs.rst index 99e8fb6..090af6e 100644 --- a/docs/source/faqs.rst +++ b/docs/source/faqs.rst @@ -18,12 +18,13 @@ Why are colours not properly reproduced? Why are images out of scale? - If *auto* :term:`cell ratio` is supported and enabled, - - Use :confval:`swap win size` or the ``--swap-win-size`` command-line option. + - Use :confval:`swap win size` or :option:`--swap-win-size `. - If the above doesn't work, then open a new issue `here `_ with adequate details. - Otherwise, - - Adjust the :term:`cell ratio` using :confval:`cell ratio` or the ``-C | --cell-ratio`` command-line option. + - Adjust the :term:`cell ratio` using :confval:`cell ratio` or + :option:`-C | --cell-ratio `. Why is the TUI unresponsive or slow in drawing images? - Drawing (not rendering) speed is **entirely** dependent on the terminal emulator itself. diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst index c259932..4328658 100644 --- a/docs/source/glossary.rst +++ b/docs/source/glossary.rst @@ -21,12 +21,12 @@ Below are definitions of terms used in the CLI help text, info/warning/error mes horizontal alignment The horizontal position of a primary :term:`render` output within its :term:`padding width`. - .. seealso:: ``--h-align`` + .. seealso:: :option:`--h-align ` vertical alignment The vertical position of a primary :term:`render` output within its :term:`padding height`. - .. seealso:: ``--v-align`` + .. seealso:: :option:`--v-align ` allowance The amount of space to be left unused on the terminal screen. @@ -34,17 +34,17 @@ Below are definitions of terms used in the CLI help text, info/warning/error mes horizontal allowance The amount of **columns** to be left unused on the terminal screen. - .. seealso:: ``--h-allow`` + .. seealso:: :option:`--h-allow ` vertical allowance The amount of **lines** to be left unused on the terminal screen. - .. seealso:: ``--v-allow`` + .. seealso:: :option:`--v-allow ` alpha threshold Alpha ratio/value above which a pixel is taken as **opaque** (applies only to text-based render styles). - .. seealso:: ``--alpha`` + .. seealso:: :option:`-A | --alpha ` animated Having multiple frames. @@ -89,14 +89,14 @@ Below are definitions of terms used in the CLI help text, info/warning/error mes Excess columns on either or both sides of the render output (depending on the :term:`horizontal alignment`) will be filled with spaces. - .. seealso:: ``--pad-width`` + .. seealso:: :option:`--pad-width ` padding height Amount of **lines** within which to fit a primary :term:`render` output. Excess lines on either or both sides of the render output (depending on the :term:`vertical alignment`) will be filled with spaces. - .. seealso:: ``--pad-height`` + .. seealso:: :option:`--pad-height ` render style render styles diff --git a/docs/source/issues.rst b/docs/source/issues.rst index b541724..9e9e7dd 100644 --- a/docs/source/issues.rst +++ b/docs/source/issues.rst @@ -6,7 +6,7 @@ Known Issues (tested in Windows Terminal and MinTTY). See the `library`_\'s :external+term_image:doc:`issues` for details. - In CLI mode, use the ``--h-allow`` option to specify a horizontal allowance. + In CLI mode, use :option:`--h-allow ` to specify a horizontal allowance. 3. Some animations with the **kitty** render style within the **Kitty terminal emulator** might be glitchy at the moment. diff --git a/docs/source/tui.rst b/docs/source/tui.rst index d20be48..9b7d799 100644 --- a/docs/source/tui.rst +++ b/docs/source/tui.rst @@ -52,7 +52,7 @@ The following are the key components that make up the UI. * Immediately above the *Action/Key Bar*. * Notifications about various events are displayed here. * Hidden in full image views. - * Hidden in all views, in QUIET mode (``--quiet``). + * Hidden in all views, in QUIET mode (:option:`-q | --quiet `). * **Action/Key Bar**: @@ -69,7 +69,7 @@ The following are the key components that make up the UI. * Used for debugging. * This is a 1-line bar immediately above the action/key bar. - * Only shows (in all views) when the ``--debug`` option is specified. + * Only shows (in all views) when :option:`--debug ` is specified. Full/Maximized image views consist of only the *view* and *action/key bar* components. diff --git a/src/termvisage/parsers.py b/src/termvisage/parsers.py index 1832576..20b170c 100644 --- a/src/termvisage/parsers.py +++ b/src/termvisage/parsers.py @@ -11,12 +11,18 @@ from .config import config_options +def rst_role_repl(match): + if match.group(1) == "option": + return f"`{match.group(2)}`" + return match.group(2) + + def strip_markup(string: str) -> str: """Strip selected reST markup from the *string*.""" if string: string = string.replace("``", "`") for pattern, repl in ( - (r":(\w+):`(.+?)( <.+>)?`", r"\2"), + (r":(\w+):`(.+?)( <.+>)?`", rst_role_repl), (r"\*\*(.+)\*\*", r"\1"), (r"\*(.+)\*", r"\1"), (r" \[.+\]_", ""), @@ -26,8 +32,9 @@ def strip_markup(string: str) -> str: return string -# Parser epilog, group descriptions and argument help may use reStructuredText markup. -# Ensure any markup used is stripped in `strip_markup()`. +# Parser epilog, group descriptions and argument help may contain reStructuredText +# markup. +# Ensure any markup used is stripped by `strip_markup()`. parser = ArgumentParser( prog="termvisage", @@ -121,7 +128,10 @@ def strip_markup(string: str) -> str: action="store_false", default=None, dest="swap_win_size", - help="Unlike ``--swap-win-size``, use the reported window size as-is (default)", + help=( + "Unlike :option:`--swap-win-size `, use the " + "reported window size as-is (default)" + ), ) mode_options = general.add_mutually_exclusive_group() @@ -233,8 +243,8 @@ def strip_markup(string: str) -> str: # CLI-only cli_options = parser.add_argument_group( "CLI-only Options", - "These options apply only when there is only one valid image source or ``--cli`` " - "is specified", + "These options apply only when there is only one valid image source or " + ":option:`--cli ` is specified", ) cli_options.add_argument( "--h-allow", @@ -261,7 +271,8 @@ def strip_markup(string: str) -> str: action="store_true", help=( "Allow an image's height to be greater than the :term:`terminal height`. " - "Not needed when ``--fit-to-width`` is specified." + "Not needed when :option:`--fit-to-width ` is " + "specified." ), ) cli_options.add_argument( @@ -270,7 +281,8 @@ def strip_markup(string: str) -> str: action="store_true", help=( "Allow an image's size to be greater than the :term:`terminal size` " - "(To be used with ``-w``, ``-h`` or ``--original-size``)" + "(To be used with :option:`-w `, :option:`-h ` " + "or :option:`--original-size `)" ), ) cli_options.add_argument( @@ -278,7 +290,10 @@ def strip_markup(string: str) -> str: "--scale", type=float, metavar="N", - help="Image :term:`scale` (overrides ``-x`` and ``-y``) [#]_", + help=( + "Image :term:`scale` (overrides :option:`-x ` and " + ":option:`-y `) [#]_" + ), ) cli_options.add_argument( "-x", @@ -299,7 +314,7 @@ def strip_markup(string: str) -> str: cli_options.add_argument( "--max-pixels-cli", action="store_true", - help=("Apply ``--max-pixels`` in CLI mode"), + help=("Apply :option:`--max-pixels ` in CLI mode"), ) # Sizing @@ -339,7 +354,8 @@ def strip_markup(string: str) -> str: dest="auto_size", help=( "Fit each image to the :term:`available ` :term:`terminal " - "width`, ``--v-allow`` has no effect i.e :term:`vertical allowance` is ignored" + "width`, :option:`--v-allow ` has no effect i.e " + ":term:`vertical allowance` is ignored" ), ) size_options.add_argument( @@ -348,8 +364,8 @@ def strip_markup(string: str) -> str: const=Size.ORIGINAL, dest="auto_size", help=( - "Render each image using its original size (See ``--oversize``, " - "**USE WITH CAUTION!**)" + "Render each image using its original size " + "(See :option:`--oversize `, **USE WITH CAUTION!**)" ), ) @@ -398,7 +414,7 @@ def strip_markup(string: str) -> str: tui_options = parser.add_argument_group( "TUI-only Options", "These options apply only when there is at least one valid directory source, " - "multiple valid sources or ``--tui`` is specified", + "multiple valid sources or :option:`--tui ` is specified", ) tui_options.add_argument( @@ -497,7 +513,8 @@ def strip_markup(string: str) -> str: # Logging log_options_ = parser.add_argument_group( "Logging Options", - "**NOTE:** All these, except ``-l | --log-file``, are mutually exclusive", + "**NOTE:** All these, except :option:`-l | --log-file `, " + "are mutually exclusive", ) log_options = log_options_.add_mutually_exclusive_group() @@ -528,12 +545,15 @@ def strip_markup(string: str) -> str: log_options.add_argument( "--verbose-log", action="store_true", - help="Like ``--verbose`` but only applies to the log file", + help=( + "Like :option:`--verbose ` but only applies to the " + "log file" + ), ) log_options.add_argument( "--debug", action="store_true", - help="Implies ``--log-level=DEBUG`` with verbosity", + help="Implies :option:`--log-level=DEBUG ` with verbosity", ) # Positional