From 3a60a0b32da7b3647032cda64f68551f9e43771f Mon Sep 17 00:00:00 2001 From: jaimergp Date: Sun, 24 Nov 2024 23:46:16 +0100 Subject: [PATCH 1/9] dump schema descriptions --- menuinst/_schema.py | 778 ++++++++++++++++++----------- menuinst/data/menuinst.schema.json | 129 ++++- 2 files changed, 602 insertions(+), 305 deletions(-) diff --git a/menuinst/_schema.py b/menuinst/_schema.py index 560de6b3..a1d49cce 100644 --- a/menuinst/_schema.py +++ b/menuinst/_schema.py @@ -3,8 +3,10 @@ """ # flake8: noqa +# pyright: reportInvalidTypeForm=false, reportCallIssue=false, reportGeneralTypeIssues=false import json +from inspect import cleandoc from logging import getLogger from pathlib import Path from pprint import pprint @@ -34,10 +36,14 @@ class MenuItemNameDict(BaseModel): such as the target environment. """ - target_environment_is_base: Optional[constr(min_length=1)] = None - "Name when target environment is the base environment." - target_environment_is_not_base: Optional[constr(min_length=1)] = None - "Name when target environment is not the base environment." + target_environment_is_base: Optional[constr(min_length=1)] = Field( + None, + description="Name when target environment is the base environment.", + ) + target_environment_is_not_base: Optional[constr(min_length=1)] = Field( + None, + description="Name when target environment is not the base environment.", + ) class BasePlatformSpecific(BaseModel): @@ -49,69 +55,102 @@ class BasePlatformSpecific(BaseModel): * Default value is always ``None``. """ - name: Optional[Union[constr(min_length=1), MenuItemNameDict]] = None - """ - The name of the menu item. Can be a dictionary if the name depends on - installation parameters. See :class:`MenuItemNameDict` for details. - """ - description: Optional[str] = None - "A longer description of the menu item. Shown on popup messages." - icon: Optional[constr(min_length=1)] = None - "Path to the file representing or containing the icon." - command: Optional[conlist(str, min_items=1)] = None - """ - Command to run with the menu item, expressed as a - list of strings where each string is an argument. - """ - working_dir: Optional[constr(min_length=1)] = None - """ - Working directory for the running process. - Defaults to user directory on each platform. - """ - precommand: Optional[constr(min_length=1)] = None - """ - (Simple, preferrably single-line) logic to run before the command is run. - Runs before the env is activated, if that applies. - """ - precreate: Optional[constr(min_length=1)] = None - "(Simple, preferrably single-line) logic to run before the shortcut is created." - activate: Optional[bool] = None - "Whether to activate the target environment before running ``command``." - terminal: Optional[bool] = None - """ - Whether run the program in a terminal/console or not. - On Windows, it only has an effect if ``activate`` is true. - On MacOS, the application will ignore command-line arguments. - """ + name: Optional[Union[constr(min_length=1), MenuItemNameDict]] = Field( + None, + description=cleandoc(""" + The name of the menu item. Can be a dictionary if the name depends on + installation parameters. See :class:`MenuItemNameDict` for details. + """), + ) + description: Optional[str] = Field( + None, + description="A longer description of the menu item. Shown on popup messages.", + ) + icon: Optional[constr(min_length=1)] = Field( + None, + description="Path to the file representing or containing the icon.", + ) + command: Optional[conlist(str, min_items=1)] = Field( + None, + description=cleandoc(""" + Command to run with the menu item, expressed as a + list of strings where each string is an argument. + """), + ) + working_dir: Optional[constr(min_length=1)] = Field( + None, + description=cleandoc(""" + Working directory for the running process. + Defaults to user directory on each platform. + """), + ) + precommand: Optional[constr(min_length=1)] = Field( + None, + description=cleandoc(""" + (Simple, preferrably single-line) logic to run before the command is run. + Runs before the env is activated, if that applies. + """), + ) + precreate: Optional[constr(min_length=1)] = Field( + None, + description="(Simple, preferrably single-line) logic to run before the shortcut is created.", + ) + activate: Optional[bool] = Field( + None, + description="Whether to activate the target environment before running ``command``.", + ) + terminal: Optional[bool] = Field( + None, + description=cleandoc(""" + Whether run the program in a terminal/console or not. + On Windows, it only has an effect if ``activate`` is true. + On MacOS, the application will ignore command-line arguments. + """), + ) class Windows(BasePlatformSpecific): "Windows-specific instructions. You can override global keys here if needed" - desktop: Optional[bool] = True - "Whether to create a desktop icon in addition to the Start Menu item." - quicklaunch: Optional[bool] = False - "DEPRECATED. Whether to create a quick launch icon in addition to the Start Menu item." - terminal_profile: constr(min_length=1) = None - """ - Name of the Windows Terminal profile to create. - This name must be unique across multiple installations because - menuinst will overwrite Terminal profiles with the same name. - """ - url_protocols: Optional[List[constr(regex=r"\S+")]] = None - "URL protocols that will be associated with this program." - file_extensions: Optional[List[constr(regex=r"\.\S*")]] = None - "File extensions that will be associated with this program." - app_user_model_id: Optional[constr(regex=r"\S+\.\S+", max_length=128)] = None - """ - Identifier used in Windows 7 and above to associate processes, files and windows with a - particular application. If your shortcut produces duplicated icons, you need to define this - field. If not set, it will default to ``Menuinst.``. - - See `AppUserModelID docs - `__ - for more information on the required string format. - """ + desktop: Optional[bool] = Field( + True, + description="Whether to create a desktop icon in addition to the Start Menu item.", + ) + quicklaunch: Optional[bool] = Field( + False, + description=cleandoc(""" + DEPRECATED. Whether to create a quick launch icon in addition to the Start Menu item. + """), + deprecated=True, + ) + terminal_profile: constr(min_length=1) = Field( + None, + description=cleandoc(""" + Name of the Windows Terminal profile to create. + This name must be unique across multiple installations because + menuinst will overwrite Terminal profiles with the same name. + """), + ) + url_protocols: Optional[List[constr(regex=r"\S+")]] = Field( + None, + description="URL protocols that will be associated with this program.", + ) + file_extensions: Optional[List[constr(regex=r"\.\S*")]] = Field( + None, + description="File extensions that will be associated with this program.", + ) + app_user_model_id: Optional[constr(regex=r"\S+\.\S+", max_length=128)] = Field( + None, + description=cleandoc(""" + Identifier used in Windows 7 and above to associate processes, files and windows with a + particular application. If your shortcut produces duplicated icons, you need to define this + field. If not set, it will default to ``Menuinst.``. + + See `AppUserModelID docs + `__ + for more information on the required string format. + """), + ) class Linux(BasePlatformSpecific): @@ -123,79 +162,115 @@ class Linux(BasePlatformSpecific): for more details. """ - Categories: Optional[Union[List[str], constr(regex=r"^.+;$")]] = None - """ - Categories in which the entry should be shown in a menu. - "See 'Registered categories' in the `Menu Spec - `__. - """ - DBusActivatable: Optional[bool] = None - "A boolean value specifying if D-Bus activation is supported for this application." - GenericName: Optional[str] = None - """ - Generic name of the application; e.g. if the name is 'conda', - this would be 'Package Manager'. - """ - Hidden: Optional[bool] = None - "Disable shortcut, signaling a missing resource." - Implements: Optional[Union[List[str], constr(regex=r"^.+;$")]] = None - """ - List of supported interfaces. See 'Interfaces' in `Desktop Entry Spec - `__. - """ - Keywords: Optional[Union[List[str], constr(regex=r"^.+;$")]] = None - "Additional terms to describe this shortcut to aid in searching." - MimeType: Optional[Union[List[str], constr(regex=r"^.+;$")]] = None - """ - The MIME type(s) supported by this application. - Note this includes file types and URL protocols. - For URL protocols, use ``x-scheme-handler/your-protocol-here``. - For example, if you want to register ``menuinst:``, you would - include ``x-scheme-handler/menuinst``. - """ - NoDisplay: Optional[bool] = None - """ - Do not show this item in the menu. Useful to associate MIME types - and other registrations, without having an actual clickable item. - Not to be confused with 'Hidden'. - """ - NotShowIn: Optional[Union[List[str], constr(regex=r"^.+;$")]] = None - """ - Desktop environments that should NOT display this item. - It'll check against ``$XDG_CURRENT_DESKTOP``." - """ - OnlyShowIn: Optional[Union[List[str], constr(regex=r"^.+;$")]] = None - """ - Desktop environments that should display this item. - It'll check against ``$XDG_CURRENT_DESKTOP``. - """ - PrefersNonDefaultGPU: Optional[bool] = None - "Hint that the app prefers to be run on a more powerful discrete GPU if available." - SingleMainWindow: Optional[bool] = None - """ - Do not show the 'New Window' option in the app's context menu. - """ - StartupNotify: Optional[bool] = None - """ - Advanced. See `Startup Notification spec - `__. - """ - StartupWMClass: Optional[str] = None - """ - Advanced. See `Startup Notification spec - `__. - """ - TryExec: Optional[str] = None - """ - Filename or absolute path to an executable file on disk used to - determine if the program is actually installed and can be run. If the test - fails, the shortcut might be ignored / hidden. - """ - glob_patterns: Optional[Dict[str, constr(regex=r".*\*.*")]] = None - """ - Map of custom MIME types to their corresponding glob patterns (e.g. ``*.txt``). - Only needed if you define custom MIME types in ``MimeType``. - """ + Categories: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( + None, + description=cleandoc(""" + Categories in which the entry should be shown in a menu. + "See 'Registered categories' in the `Menu Spec + `__. + """), + ) + DBusActivatable: Optional[bool] = Field( + None, + description=cleandoc( + """A boolean value specifying if D-Bus activation is supported for this application. + """), + ) + GenericName: Optional[str] = Field( + None, + description=cleandoc(""" + Generic name of the application; e.g. if the name is 'conda', + this would be 'Package Manager'. + """), + ) + Hidden: Optional[bool] = Field( + None, + description="Disable shortcut, signaling a missing resource.", + ) + Implements: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( + None, + description=cleandoc(""" + List of supported interfaces. See 'Interfaces' in `Desktop Entry Spec + `__. + """), + ) + Keywords: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( + None, + description="Additional terms to describe this shortcut to aid in searching.", + ) + MimeType: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( + None, + description=cleandoc(""" + The MIME type(s) supported by this application. + Note this includes file types and URL protocols. + For URL protocols, use ``x-scheme-handler/your-protocol-here``. + For example, if you want to register ``menuinst:``, you would + include ``x-scheme-handler/menuinst``. + """), + ) + NoDisplay: Optional[bool] = Field( + None, + description=cleandoc(""" + Do not show this item in the menu. Useful to associate MIME types + and other registrations, without having an actual clickable item. + Not to be confused with 'Hidden'. + """), + ) + NotShowIn: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( + None, + description=cleandoc(""" + Desktop environments that should NOT display this item. + It'll check against ``$XDG_CURRENT_DESKTOP``." + """), + ) + OnlyShowIn: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( + None, + description=cleandoc(""" + Desktop environments that should display this item. + It'll check against ``$XDG_CURRENT_DESKTOP``. + """), + ) + PrefersNonDefaultGPU: Optional[bool] = Field( + None, + description=cleandoc(""" + Hint that the app prefers to be run on a more powerful discrete GPU if available. + """), + ) + SingleMainWindow: Optional[bool] = Field( + None, + description=cleandoc(""" + Do not show the 'New Window' option in the app's context menu. + """), + ) + StartupNotify: Optional[bool] = Field( + None, + description=cleandoc(""" + Advanced. See `Startup Notification spec + `__. + """), + ) + StartupWMClass: Optional[str] = Field( + None, + description=cleandoc(""" + Advanced. See `Startup Notification spec + `__. + """), + ) + TryExec: Optional[str] = Field( + None, + description=cleandoc(""" + Filename or absolute path to an executable file on disk used to + determine if the program is actually installed and can be run. If the test + fails, the shortcut might be ignored / hidden. + """), + ) + glob_patterns: Optional[Dict[str, constr(regex=r".*\*.*")]] = Field( + None, + description=cleandoc(""" + Map of custom MIME types to their corresponding glob patterns (e.g. ``*.txt``). + Only needed if you define custom MIME types in ``MimeType``. + """), + ) class MacOS(BasePlatformSpecific): @@ -209,133 +284,203 @@ class MacOS(BasePlatformSpecific): class CFBundleURLTypesModel(BaseModel): "Describes a URL scheme associated with the app." - CFBundleTypeRole: Optional[Literal["Editor", "Viewer", "Shell", "None"]] = None - "This key specifies the app's role with respect to the URL." - CFBundleURLSchemes: List[str] = ... - "URL schemes / protocols handled by this type (e.g. 'mailto').", - CFBundleURLName: Optional[str] = None - "Abstract name for this URL type. Uniqueness recommended.", - CFBundleURLIconFile: Optional[str] = None - "Name of the icon image file (minus the .icns extension).", + + CFBundleTypeRole: Optional[Literal["Editor", "Viewer", "Shell", "None"]] = Field( + None, + description="This key specifies the app's role with respect to the URL.", + ) + CFBundleURLSchemes: List[str] = Field( + ..., + description="URL schemes / protocols handled by this type (e.g. 'mailto').", + ) + CFBundleURLName: Optional[str] = Field( + None, + description="Abstract name for this URL type. Uniqueness recommended.", + ) + CFBundleURLIconFile: Optional[str] = Field( + None, + description="Name of the icon image file (minus the .icns extension).", + ) class CFBundleDocumentTypesModel(BaseModel): "Describes a document type associated with the app." - CFBundleTypeIconFile: Optional[str] = None - "Name of the icon image file (minus the .icns extension).", - CFBundleTypeName: str = ... - "Abstract name for this document type. Uniqueness recommended.", - CFBundleTypeRole: Optional[Literal["Editor", "Viewer", "Shell", "None"]] = None - "This key specifies the app's role with respect to the type." - LSItemContentTypes: List[str] = ... - """ - List of UTI strings defining a supported file type; e.g. for - PNG files, use 'public.png'. See `UTI Reference - `__ - for more info about the system-defined UTIs. Custom UTIs can be - defined via 'UTExportedTypeDeclarations'. UTIs defined by other - apps (not the system) need to be imported via 'UTImportedTypeDeclarations'. - - See `Fun with UTIs `__ for more info. - """ - LSHandlerRank: Literal["Owner", "Default", "Alternate"] = ... - """ - Determines how Launch Services ranks this app among the apps - that declare themselves editors or viewers of files of this type. - """ + + CFBundleTypeIconFile: Optional[str] = Field( + None, + description="Name of the icon image file (minus the .icns extension).", + ) + CFBundleTypeName: str = Field( + ..., + description="Abstract name for this document type. Uniqueness recommended.", + ) + CFBundleTypeRole: Optional[Literal["Editor", "Viewer", "Shell", "None"]] = Field( + None, description="This key specifies the app's role with respect to the type." + ) + LSItemContentTypes: List[str] = Field( + ..., + description=cleandoc(""" + List of UTI strings defining a supported file type; e.g. for + PNG files, use 'public.png'. See `UTI Reference + `__ + for more info about the system-defined UTIs. Custom UTIs can be + defined via 'UTExportedTypeDeclarations'. UTIs defined by other + apps (not the system) need to be imported via 'UTImportedTypeDeclarations'. + + See `Fun with UTIs `__ for more info. + """), + ) + LSHandlerRank: Literal["Owner", "Default", "Alternate"] = Field( + ..., + description=cleandoc(""" + Determines how Launch Services ranks this app among the apps + that declare themselves editors or viewers of files of this type. + """), + ) class UTTypeDeclarationModel(BaseModel): - UTTypeConformsTo: List[str] = ... - "The Uniform Type Identifier types that this type conforms to." - UTTypeDescription: Optional[str] = None - "A description for this type." - UTTypeIconFile: Optional[str] = None - "The bundle icon resource to associate with this type." - UTTypeIdentifier: str = ... - "The Uniform Type Identifier to assign to this type." - UTTypeReferenceURL: Optional[str] = None - "The webpage for a reference document that describes this type." - UTTypeTagSpecification: Dict[str, List[str]] = ... - "A dictionary defining one or more equivalent type identifiers." - - CFBundleDisplayName: Optional[str] = None - """ - Display name of the bundle, visible to users and used by Siri. If - not provided, 'menuinst' will use the 'name' field. - """ - CFBundleIdentifier: Optional[constr(regex=r"^[A-z0-9\-\.]+$")] = None - """ - Unique identifier for the shortcut. Typically uses a reverse-DNS format. - If not provided, 'menuinst' will generate one from the 'name' field. - """ - CFBundleName: Optional[constr(max_length=16)] = None - """ - Short name of the bundle. May be used if ``CFBundleDisplayName`` is - absent. If not provided, 'menuinst' will generate one from the 'name' field. - """ - CFBundleSpokenName: Optional[str] = None - """ - Suitable replacement for text-to-speech operations on the app. - For example, 'my app one two three' instead of 'MyApp123'. - """ - CFBundleVersion: Optional[constr(regex=r"^\S+$")] = None - """ - Build version number for the bundle. In the context of 'menuinst' - this can be used to signal a new version of the menu item for the same - application version. - """ - CFBundleURLTypes: Optional[List[CFBundleURLTypesModel]] = None - """ - URL types supported by this app. Requires setting `event_handler` too. - Note this feature requires macOS 10.14.4 or above. - """ - CFBundleDocumentTypes: Optional[List[CFBundleDocumentTypesModel]] = None - """ - Document types supported by this app. Requires setting `event_handler` too. - Requires macOS 10.14.4 or above. - """ - LSApplicationCategoryType: Optional[constr(regex=r"^public\.app-category\.\S+$")] = None - "The App Store uses this string to determine the appropriate categorization." - LSBackgroundOnly: Optional[bool] = None - "Specifies whether this app runs only in the background." - LSEnvironment: Optional[Dict[str, str]] = None - "List of key-value pairs used to define environment variables.", - LSMinimumSystemVersion: Optional[constr(regex=r"^\d+\.\d+\.\d+$")] = None - """ - Minimum version of macOS required for this app to run, as ``x.y.z``. - For example, for macOS v10.4 and later, use ``10.4.0``. - """ - LSMultipleInstancesProhibited: Optional[bool] = None - "Whether an app is prohibited from running simultaneously in multiple user sessions." - LSRequiresNativeExecution: Optional[bool] = None - """ - If true, prevent a universal binary from being run under - Rosetta emulation on an Intel-based Mac. - """ - NSSupportsAutomaticGraphicsSwitching: Optional[bool] = None - """If true, allows an OpenGL app to utilize the integrated GPU.""" - UTExportedTypeDeclarations: Optional[List[UTTypeDeclarationModel]] = None - "The uniform type identifiers owned and exported by the app." - UTImportedTypeDeclarations: Optional[List[UTTypeDeclarationModel]] = None - "The uniform type identifiers inherently supported, but not owned, by the app." - entitlements: Optional[List[constr(regex=r"[a-z0-9\.\-]+")]] = None - """ - List of permissions to request for the launched application. - See `the entitlements docs `__ - for a full list of possible values. - """ + UTTypeConformsTo: List[str] = Field( + ..., + description="The Uniform Type Identifier types that this type conforms to.", + ) + UTTypeDescription: Optional[str] = Field( + None, + description="A description for this type.", + ) + UTTypeIconFile: Optional[str] = Field( + None, + description="The bundle icon resource to associate with this type.", + ) + UTTypeIdentifier: str = Field( + ..., + description="The Uniform Type Identifier to assign to this type.", + ) + UTTypeReferenceURL: Optional[str] = Field( + None, + description="The webpage for a reference document that describes this type.", + ) + UTTypeTagSpecification: Dict[str, List[str]] = Field( + ..., + description="A dictionary defining one or more equivalent type identifiers.", + ) + + CFBundleDisplayName: Optional[str] = Field( + None, + description=cleandoc(""" + Display name of the bundle, visible to users and used by Siri. If + not provided, 'menuinst' will use the 'name' field. + """), + ) + CFBundleIdentifier: Optional[constr(regex=r"^[A-z0-9\-\.]+$")] = Field( + None, + description=cleandoc(""" + Unique identifier for the shortcut. Typically uses a reverse-DNS format. + If not provided, 'menuinst' will generate one from the 'name' field. + """), + ) + CFBundleName: Optional[constr(max_length=16)] = Field( + None, + description=cleandoc(""" + Short name of the bundle. May be used if ``CFBundleDisplayName`` is + absent. If not provided, 'menuinst' will generate one from the 'name' field. + """), + ) + CFBundleSpokenName: Optional[str] = Field( + None, + description=cleandoc(""" + Suitable replacement for text-to-speech operations on the app. + For example, 'my app one two three' instead of 'MyApp123'. + """), + ) + CFBundleVersion: Optional[constr(regex=r"^\S+$")] = Field( + None, + description=cleandoc(""" + Build version number for the bundle. In the context of 'menuinst' + this can be used to signal a new version of the menu item for the same + application version. + """), + ) + CFBundleURLTypes: Optional[List[CFBundleURLTypesModel]] = Field( + None, + description=cleandoc(""" + URL types supported by this app. Requires setting `event_handler` too. + Note this feature requires macOS 10.14.4 or above. + """), + ) + CFBundleDocumentTypes: Optional[List[CFBundleDocumentTypesModel]] = Field( + None, + description=cleandoc(""" + Document types supported by this app. Requires setting `event_handler` too. + Requires macOS 10.14.4 or above. + """), + ) + LSApplicationCategoryType: Optional[constr(regex=r"^public\.app-category\.\S+$")] = Field( + None, + description="The App Store uses this string to determine the appropriate categorization.", + ) + LSBackgroundOnly: Optional[bool] = Field( + None, + description="Specifies whether this app runs only in the background.", + ) + LSEnvironment: Optional[Dict[str, str]] = Field( + None, + description="List of key-value pairs used to define environment variables.", + ) + LSMinimumSystemVersion: Optional[constr(regex=r"^\d+\.\d+\.\d+$")] = Field( + None, + description=cleandoc(""" + Minimum version of macOS required for this app to run, as ``x.y.z``. + For example, for macOS v10.4 and later, use ``10.4.0``. + """), + ) + LSMultipleInstancesProhibited: Optional[bool] = Field( + None, + description=cleandoc(""" + Whether an app is prohibited from running simultaneously in multiple user sessions." + """), + ) + LSRequiresNativeExecution: Optional[bool] = Field( + None, + description=cleandoc(""" + If true, prevent a universal binary from being run under + Rosetta emulation on an Intel-based Mac. + """), + ) + NSSupportsAutomaticGraphicsSwitching: Optional[bool] = Field( + None, + description="If true, allows an OpenGL app to utilize the integrated GPU.", + ) + UTExportedTypeDeclarations: Optional[List[UTTypeDeclarationModel]] = Field( + None, description="The uniform type identifiers owned and exported by the app." + ) + UTImportedTypeDeclarations: Optional[List[UTTypeDeclarationModel]] = Field( + None, + description="The uniform type identifiers inherently supported, but not owned, by the app.", + ) + entitlements: Optional[List[constr(regex=r"[a-z0-9\.\-]+")]] = Field( + None, + description=cleandoc(""" + List of permissions to request for the launched application. + See `the entitlements docs `__ + for a full list of possible values. + """), + ) link_in_bundle: Optional[Dict[constr(min_length=1), constr(regex=r"^(?!\/)(?!\.\./).*")]] = ( - None + Field( + None, + description=cleandoc(""" + Paths that should be symlinked into the shortcut app bundle. + It takes a mapping of source to destination paths. Destination paths must be + relative. Placeholder ``{{ MENU_ITEM_LOCATION }}`` can be useful. + """), + ) + ) + event_handler: Optional[constr(min_length=1)] = Field( + None, + description=cleandoc(""" + Required shell script logic to handle opened URL payloads. + Note this feature requires macOS 10.14.4 or above. + """), ) - """ - Paths that should be symlinked into the shortcut app bundle. - It takes a mapping of source to destination paths. Destination paths must be - relative. Placeholder ``{{ MENU_ITEM_LOCATION }}`` can be useful. - """ - event_handler: Optional[constr(min_length=1)] = None - """ - Required shell script logic to handle opened URL payloads. - Note this feature requires macOS 10.14.4 or above. - """ class Platforms(BaseModel): @@ -346,53 +491,80 @@ class Platforms(BaseModel): (sans ``platforms`` itself), in case overrides are needed. """ - linux: Optional[Linux] - "Options for Linux. See :class:`Linux` model for details." - osx: Optional[MacOS] - "Options for macOS. See :class:`MacOS` model for details." - win: Optional[Windows] - "Options for Windows. See :class:`Windows` model for details." + linux: Optional[Linux] = Field( + description="Options for Linux. See :class:`Linux` model for details." + ) + osx: Optional[MacOS] = Field( + description="Options for macOS. See :class:`MacOS` model for details." + ) + win: Optional[Windows] = Field( + description="Options for Windows. See :class:`Windows` model for details." + ) class MenuItem(BaseModel): "Instructions to create a menu item across operating systems." - name: Union[constr(min_length=1), MenuItemNameDict] = ... - """ - The name of the menu item. Can be a dictionary if the name depends on - installation parameters. See :class:`MenuItemNameDict` for details. - """ - description: str = ... - "A longer description of the menu item. Shown on popup messages." - command: conlist(str, min_items=1) = ... - """ - Command to run with the menu item, expressed as a - list of strings where each string is an argument. - """ - icon: Optional[constr(min_length=1)] = None - "Path to the file representing or containing the icon." - precommand: Optional[constr(min_length=1)] = None - """ - (Simple, preferrably single-line) logic to run before the command is run. - Runs before the environment is activated, if that applies. - """ - precreate: Optional[constr(min_length=1)] = None - "(Simple, preferrably single-line) logic to run before the shortcut is created." - working_dir: Optional[constr(min_length=1)] = None - """ - Working directory for the running process. - Defaults to user directory on each platform. - """ - activate: Optional[bool] = True - "Whether to activate the target environment before running ``command``." - terminal: Optional[bool] = False - """ - Whether run the program in a terminal/console or not. - On Windows, it only has an effect if ``activate`` is true. - On MacOS, the application will ignore command-line arguments. - """ - platforms: Platforms - "Platform-specific options. Presence of a platform field enables menu items in that platform." + name: Union[constr(min_length=1), MenuItemNameDict] = Field( + ..., + description=cleandoc(""" + The name of the menu item. Can be a dictionary if the name depends on + installation parameters. See :class:`MenuItemNameDict` for details. + """), + ) + description: str = Field( + ..., + description="A longer description of the menu item. Shown on popup messages.", + ) + command: conlist(str, min_items=1) = Field( + ..., + description=cleandoc(""" + Command to run with the menu item, expressed as a + list of strings where each string is an argument. + """), + ) + icon: Optional[constr(min_length=1)] = Field( + None, + description="Path to the file representing or containing the icon.", + ) + precommand: Optional[constr(min_length=1)] = Field( + None, + description=cleandoc(""" + (Simple, preferrably single-line) logic to run before the command is run. + Runs before the environment is activated, if that applies. + """), + ) + precreate: Optional[constr(min_length=1)] = Field( + None, + description=cleandoc(""" + (Simple, preferrably single-line) logic to run before the shortcut is created. + """), + ) + working_dir: Optional[constr(min_length=1)] = Field( + None, + description=cleandoc(""" + Working directory for the running process. + Defaults to user directory on each platform. + """), + ) + activate: Optional[bool] = Field( + True, + description="Whether to activate the target environment before running ``command``.", + ) + terminal: Optional[bool] = Field( + False, + description=cleandoc(""" + Whether run the program in a terminal/console or not. + On Windows, it only has an effect if ``activate`` is true. + On MacOS, the application will ignore command-line arguments. + """), + ) + platforms: Platforms = Field( + description=cleandoc(""" + Platform-specific options. Presence of a platform field enables + menu items in that platform." + """), + ) class MenuInstSchema(BaseModel): @@ -408,10 +580,14 @@ class MenuInstSchema(BaseModel): description="Standard of the JSON schema we adhere to.", alias="$schema", ) - menu_name: constr(min_length=1) = ... - "Name for the category containing the items specified in ``menu_items``." - menu_items: conlist(MenuItem, min_items=1) = ... - "List of menu entries to create across main desktop systems." + menu_name: constr(min_length=1) = Field( + ..., + description="Name for the category containing the items specified in ``menu_items``.", + ) + menu_items: conlist(MenuItem, min_items=1) = Field( + ..., + description="List of menu entries to create across main desktop systems.", + ) def dump_schema_to_json(write=True): diff --git a/menuinst/data/menuinst.schema.json b/menuinst/data/menuinst.schema.json index 9aaa3a70..0fbeb1fa 100644 --- a/menuinst/data/menuinst.schema.json +++ b/menuinst/data/menuinst.schema.json @@ -21,11 +21,13 @@ }, "menu_name": { "title": "Menu Name", + "description": "Name for the category containing the items specified in ``menu_items``.", "minLength": 1, "type": "string" }, "menu_items": { "title": "Menu Items", + "description": "List of menu entries to create across main desktop systems.", "minItems": 1, "type": "array", "items": { @@ -48,11 +50,13 @@ "properties": { "target_environment_is_base": { "title": "Target Environment Is Base", + "description": "Name when target environment is the base environment.", "minLength": 1, "type": "string" }, "target_environment_is_not_base": { "title": "Target Environment Is Not Base", + "description": "Name when target environment is not the base environment.", "minLength": 1, "type": "string" } @@ -66,6 +70,7 @@ "properties": { "name": { "title": "Name", + "description": "The name of the menu item. Can be a dictionary if the name depends on\ninstallation parameters. See :class:`MenuItemNameDict` for details.", "anyOf": [ { "type": "string", @@ -78,15 +83,18 @@ }, "description": { "title": "Description", + "description": "A longer description of the menu item. Shown on popup messages.", "type": "string" }, "icon": { "title": "Icon", + "description": "Path to the file representing or containing the icon.", "minLength": 1, "type": "string" }, "command": { "title": "Command", + "description": "Command to run with the menu item, expressed as a\nlist of strings where each string is an argument.", "minItems": 1, "type": "array", "items": { @@ -95,29 +103,35 @@ }, "working_dir": { "title": "Working Dir", + "description": "Working directory for the running process.\nDefaults to user directory on each platform.", "minLength": 1, "type": "string" }, "precommand": { "title": "Precommand", + "description": "(Simple, preferrably single-line) logic to run before the command is run.\nRuns before the env is activated, if that applies.", "minLength": 1, "type": "string" }, "precreate": { "title": "Precreate", + "description": "(Simple, preferrably single-line) logic to run before the shortcut is created.", "minLength": 1, "type": "string" }, "activate": { "title": "Activate", + "description": "Whether to activate the target environment before running ``command``.", "type": "boolean" }, "terminal": { "title": "Terminal", + "description": "Whether run the program in a terminal/console or not.\nOn Windows, it only has an effect if ``activate`` is true.\nOn MacOS, the application will ignore command-line arguments.", "type": "boolean" }, "Categories": { "title": "Categories", + "description": "Categories in which the entry should be shown in a menu.\n\"See 'Registered categories' in the `Menu Spec\n`__.", "anyOf": [ { "type": "array", @@ -133,18 +147,22 @@ }, "DBusActivatable": { "title": "Dbusactivatable", + "description": "A boolean value specifying if D-Bus activation is supported for this application.\n ", "type": "boolean" }, "GenericName": { "title": "Genericname", + "description": "Generic name of the application; e.g. if the name is 'conda',\nthis would be 'Package Manager'.", "type": "string" }, "Hidden": { "title": "Hidden", + "description": "Disable shortcut, signaling a missing resource.", "type": "boolean" }, "Implements": { "title": "Implements", + "description": "List of supported interfaces. See 'Interfaces' in `Desktop Entry Spec\n`__.", "anyOf": [ { "type": "array", @@ -160,6 +178,7 @@ }, "Keywords": { "title": "Keywords", + "description": "Additional terms to describe this shortcut to aid in searching.", "anyOf": [ { "type": "array", @@ -175,6 +194,7 @@ }, "MimeType": { "title": "Mimetype", + "description": "The MIME type(s) supported by this application.\nNote this includes file types and URL protocols.\nFor URL protocols, use ``x-scheme-handler/your-protocol-here``.\nFor example, if you want to register ``menuinst:``, you would\ninclude ``x-scheme-handler/menuinst``.", "anyOf": [ { "type": "array", @@ -190,10 +210,12 @@ }, "NoDisplay": { "title": "Nodisplay", + "description": "Do not show this item in the menu. Useful to associate MIME types\nand other registrations, without having an actual clickable item.\nNot to be confused with 'Hidden'.", "type": "boolean" }, "NotShowIn": { "title": "Notshowin", + "description": "Desktop environments that should NOT display this item.\nIt'll check against ``$XDG_CURRENT_DESKTOP``.\"", "anyOf": [ { "type": "array", @@ -209,6 +231,7 @@ }, "OnlyShowIn": { "title": "Onlyshowin", + "description": "Desktop environments that should display this item.\nIt'll check against ``$XDG_CURRENT_DESKTOP``.", "anyOf": [ { "type": "array", @@ -224,26 +247,32 @@ }, "PrefersNonDefaultGPU": { "title": "Prefersnondefaultgpu", + "description": "Hint that the app prefers to be run on a more powerful discrete GPU if available.", "type": "boolean" }, "SingleMainWindow": { "title": "Singlemainwindow", + "description": "Do not show the 'New Window' option in the app's context menu.", "type": "boolean" }, "StartupNotify": { "title": "Startupnotify", + "description": "Advanced. See `Startup Notification spec\n`__.", "type": "boolean" }, "StartupWMClass": { "title": "Startupwmclass", + "description": "Advanced. See `Startup Notification spec\n`__.", "type": "string" }, "TryExec": { "title": "Tryexec", + "description": "Filename or absolute path to an executable file on disk used to\ndetermine if the program is actually installed and can be run. If the test\nfails, the shortcut might be ignored / hidden.", "type": "string" }, "glob_patterns": { "title": "Glob Patterns", + "description": "Map of custom MIME types to their corresponding glob patterns (e.g. ``*.txt``).\nOnly needed if you define custom MIME types in ``MimeType``.", "type": "object", "additionalProperties": { "type": "string", @@ -260,6 +289,7 @@ "properties": { "CFBundleTypeRole": { "title": "Cfbundletyperole", + "description": "This key specifies the app's role with respect to the URL.", "enum": [ "Editor", "Viewer", @@ -270,6 +300,7 @@ }, "CFBundleURLSchemes": { "title": "Cfbundleurlschemes", + "description": "URL schemes / protocols handled by this type (e.g. 'mailto').", "type": "array", "items": { "type": "string" @@ -277,10 +308,12 @@ }, "CFBundleURLName": { "title": "Cfbundleurlname", + "description": "Abstract name for this URL type. Uniqueness recommended.", "type": "string" }, "CFBundleURLIconFile": { "title": "Cfbundleurliconfile", + "description": "Name of the icon image file (minus the .icns extension).", "type": "string" } }, @@ -296,14 +329,17 @@ "properties": { "CFBundleTypeIconFile": { "title": "Cfbundletypeiconfile", + "description": "Name of the icon image file (minus the .icns extension).", "type": "string" }, "CFBundleTypeName": { "title": "Cfbundletypename", + "description": "Abstract name for this document type. Uniqueness recommended.", "type": "string" }, "CFBundleTypeRole": { "title": "Cfbundletyperole", + "description": "This key specifies the app's role with respect to the type.", "enum": [ "Editor", "Viewer", @@ -314,6 +350,7 @@ }, "LSItemContentTypes": { "title": "Lsitemcontenttypes", + "description": "List of UTI strings defining a supported file type; e.g. for\nPNG files, use 'public.png'. See `UTI Reference\n`__\nfor more info about the system-defined UTIs. Custom UTIs can be\ndefined via 'UTExportedTypeDeclarations'. UTIs defined by other\napps (not the system) need to be imported via 'UTImportedTypeDeclarations'.\n\nSee `Fun with UTIs `__ for more info.", "type": "array", "items": { "type": "string" @@ -321,6 +358,7 @@ }, "LSHandlerRank": { "title": "Lshandlerrank", + "description": "Determines how Launch Services ranks this app among the apps\nthat declare themselves editors or viewers of files of this type.", "enum": [ "Owner", "Default", @@ -342,6 +380,7 @@ "properties": { "UTTypeConformsTo": { "title": "Uttypeconformsto", + "description": "The Uniform Type Identifier types that this type conforms to.", "type": "array", "items": { "type": "string" @@ -349,22 +388,27 @@ }, "UTTypeDescription": { "title": "Uttypedescription", + "description": "A description for this type.", "type": "string" }, "UTTypeIconFile": { "title": "Uttypeiconfile", + "description": "The bundle icon resource to associate with this type.", "type": "string" }, "UTTypeIdentifier": { "title": "Uttypeidentifier", + "description": "The Uniform Type Identifier to assign to this type.", "type": "string" }, "UTTypeReferenceURL": { "title": "Uttypereferenceurl", + "description": "The webpage for a reference document that describes this type.", "type": "string" }, "UTTypeTagSpecification": { "title": "Uttypetagspecification", + "description": "A dictionary defining one or more equivalent type identifiers.", "type": "object", "additionalProperties": { "type": "array", @@ -388,6 +432,7 @@ "properties": { "name": { "title": "Name", + "description": "The name of the menu item. Can be a dictionary if the name depends on\ninstallation parameters. See :class:`MenuItemNameDict` for details.", "anyOf": [ { "type": "string", @@ -400,15 +445,18 @@ }, "description": { "title": "Description", + "description": "A longer description of the menu item. Shown on popup messages.", "type": "string" }, "icon": { "title": "Icon", + "description": "Path to the file representing or containing the icon.", "minLength": 1, "type": "string" }, "command": { "title": "Command", + "description": "Command to run with the menu item, expressed as a\nlist of strings where each string is an argument.", "minItems": 1, "type": "array", "items": { @@ -417,52 +465,63 @@ }, "working_dir": { "title": "Working Dir", + "description": "Working directory for the running process.\nDefaults to user directory on each platform.", "minLength": 1, "type": "string" }, "precommand": { "title": "Precommand", + "description": "(Simple, preferrably single-line) logic to run before the command is run.\nRuns before the env is activated, if that applies.", "minLength": 1, "type": "string" }, "precreate": { "title": "Precreate", + "description": "(Simple, preferrably single-line) logic to run before the shortcut is created.", "minLength": 1, "type": "string" }, "activate": { "title": "Activate", + "description": "Whether to activate the target environment before running ``command``.", "type": "boolean" }, "terminal": { "title": "Terminal", + "description": "Whether run the program in a terminal/console or not.\nOn Windows, it only has an effect if ``activate`` is true.\nOn MacOS, the application will ignore command-line arguments.", "type": "boolean" }, "CFBundleDisplayName": { "title": "Cfbundledisplayname", + "description": "Display name of the bundle, visible to users and used by Siri. If\nnot provided, 'menuinst' will use the 'name' field.", "type": "string" }, "CFBundleIdentifier": { "title": "Cfbundleidentifier", + "description": "Unique identifier for the shortcut. Typically uses a reverse-DNS format.\nIf not provided, 'menuinst' will generate one from the 'name' field.", "pattern": "^[A-z0-9\\-\\.]+$", "type": "string" }, "CFBundleName": { "title": "Cfbundlename", + "description": "Short name of the bundle. May be used if ``CFBundleDisplayName`` is\nabsent. If not provided, 'menuinst' will generate one from the 'name' field.", "maxLength": 16, "type": "string" }, "CFBundleSpokenName": { "title": "Cfbundlespokenname", + "description": "Suitable replacement for text-to-speech operations on the app.\nFor example, 'my app one two three' instead of 'MyApp123'.", "type": "string" }, "CFBundleVersion": { "title": "Cfbundleversion", + "description": "Build version number for the bundle. In the context of 'menuinst'\nthis can be used to signal a new version of the menu item for the same\napplication version.", "pattern": "^\\S+$", "type": "string" }, "CFBundleURLTypes": { "title": "Cfbundleurltypes", + "description": "URL types supported by this app. Requires setting `event_handler` too.\nNote this feature requires macOS 10.14.4 or above.", "type": "array", "items": { "$ref": "#/definitions/CFBundleURLTypesModel" @@ -470,6 +529,7 @@ }, "CFBundleDocumentTypes": { "title": "Cfbundledocumenttypes", + "description": "Document types supported by this app. Requires setting `event_handler` too.\nRequires macOS 10.14.4 or above.", "type": "array", "items": { "$ref": "#/definitions/CFBundleDocumentTypesModel" @@ -477,15 +537,18 @@ }, "LSApplicationCategoryType": { "title": "Lsapplicationcategorytype", + "description": "The App Store uses this string to determine the appropriate categorization.", "pattern": "^public\\.app-category\\.\\S+$", "type": "string" }, "LSBackgroundOnly": { "title": "Lsbackgroundonly", + "description": "Specifies whether this app runs only in the background.", "type": "boolean" }, "LSEnvironment": { "title": "Lsenvironment", + "description": "List of key-value pairs used to define environment variables.", "type": "object", "additionalProperties": { "type": "string" @@ -493,23 +556,28 @@ }, "LSMinimumSystemVersion": { "title": "Lsminimumsystemversion", + "description": "Minimum version of macOS required for this app to run, as ``x.y.z``.\nFor example, for macOS v10.4 and later, use ``10.4.0``.", "pattern": "^\\d+\\.\\d+\\.\\d+$", "type": "string" }, "LSMultipleInstancesProhibited": { "title": "Lsmultipleinstancesprohibited", + "description": "Whether an app is prohibited from running simultaneously in multiple user sessions.\"", "type": "boolean" }, "LSRequiresNativeExecution": { "title": "Lsrequiresnativeexecution", + "description": "If true, prevent a universal binary from being run under\nRosetta emulation on an Intel-based Mac.", "type": "boolean" }, "NSSupportsAutomaticGraphicsSwitching": { "title": "Nssupportsautomaticgraphicsswitching", + "description": "If true, allows an OpenGL app to utilize the integrated GPU.", "type": "boolean" }, "UTExportedTypeDeclarations": { "title": "Utexportedtypedeclarations", + "description": "The uniform type identifiers owned and exported by the app.", "type": "array", "items": { "$ref": "#/definitions/UTTypeDeclarationModel" @@ -517,6 +585,7 @@ }, "UTImportedTypeDeclarations": { "title": "Utimportedtypedeclarations", + "description": "The uniform type identifiers inherently supported, but not owned, by the app.", "type": "array", "items": { "$ref": "#/definitions/UTTypeDeclarationModel" @@ -524,6 +593,7 @@ }, "entitlements": { "title": "Entitlements", + "description": "List of permissions to request for the launched application.\nSee `the entitlements docs `__\nfor a full list of possible values.", "type": "array", "items": { "type": "string", @@ -532,6 +602,7 @@ }, "link_in_bundle": { "title": "Link In Bundle", + "description": "Paths that should be symlinked into the shortcut app bundle.\nIt takes a mapping of source to destination paths. Destination paths must be\nrelative. Placeholder ``{{ MENU_ITEM_LOCATION }}`` can be useful.", "type": "object", "additionalProperties": { "type": "string", @@ -540,6 +611,7 @@ }, "event_handler": { "title": "Event Handler", + "description": "Required shell script logic to handle opened URL payloads.\nNote this feature requires macOS 10.14.4 or above.", "minLength": 1, "type": "string" } @@ -553,6 +625,7 @@ "properties": { "name": { "title": "Name", + "description": "The name of the menu item. Can be a dictionary if the name depends on\ninstallation parameters. See :class:`MenuItemNameDict` for details.", "anyOf": [ { "type": "string", @@ -565,15 +638,18 @@ }, "description": { "title": "Description", + "description": "A longer description of the menu item. Shown on popup messages.", "type": "string" }, "icon": { "title": "Icon", + "description": "Path to the file representing or containing the icon.", "minLength": 1, "type": "string" }, "command": { "title": "Command", + "description": "Command to run with the menu item, expressed as a\nlist of strings where each string is an argument.", "minItems": 1, "type": "array", "items": { @@ -582,44 +658,54 @@ }, "working_dir": { "title": "Working Dir", + "description": "Working directory for the running process.\nDefaults to user directory on each platform.", "minLength": 1, "type": "string" }, "precommand": { "title": "Precommand", + "description": "(Simple, preferrably single-line) logic to run before the command is run.\nRuns before the env is activated, if that applies.", "minLength": 1, "type": "string" }, "precreate": { "title": "Precreate", + "description": "(Simple, preferrably single-line) logic to run before the shortcut is created.", "minLength": 1, "type": "string" }, "activate": { "title": "Activate", + "description": "Whether to activate the target environment before running ``command``.", "type": "boolean" }, "terminal": { "title": "Terminal", + "description": "Whether run the program in a terminal/console or not.\nOn Windows, it only has an effect if ``activate`` is true.\nOn MacOS, the application will ignore command-line arguments.", "type": "boolean" }, "desktop": { "title": "Desktop", + "description": "Whether to create a desktop icon in addition to the Start Menu item.", "default": true, "type": "boolean" }, "quicklaunch": { "title": "Quicklaunch", + "description": "DEPRECATED. Whether to create a quick launch icon in addition to the Start Menu item.", "default": false, + "deprecated": true, "type": "boolean" }, "terminal_profile": { "title": "Terminal Profile", + "description": "Name of the Windows Terminal profile to create.\nThis name must be unique across multiple installations because\nmenuinst will overwrite Terminal profiles with the same name.", "minLength": 1, "type": "string" }, "url_protocols": { "title": "Url Protocols", + "description": "URL protocols that will be associated with this program.", "type": "array", "items": { "type": "string", @@ -628,6 +714,7 @@ }, "file_extensions": { "title": "File Extensions", + "description": "File extensions that will be associated with this program.", "type": "array", "items": { "type": "string", @@ -636,6 +723,7 @@ }, "app_user_model_id": { "title": "App User Model Id", + "description": "Identifier used in Windows 7 and above to associate processes, files and windows with a\nparticular application. If your shortcut produces duplicated icons, you need to define this\nfield. If not set, it will default to ``Menuinst.``.\n\nSee `AppUserModelID docs\n`__\nfor more information on the required string format.", "maxLength": 128, "pattern": "\\S+\\.\\S+", "type": "string" @@ -649,13 +737,31 @@ "type": "object", "properties": { "linux": { - "$ref": "#/definitions/Linux" + "title": "Linux", + "description": "Options for Linux. See :class:`Linux` model for details.", + "allOf": [ + { + "$ref": "#/definitions/Linux" + } + ] }, "osx": { - "$ref": "#/definitions/MacOS" + "title": "Osx", + "description": "Options for macOS. See :class:`MacOS` model for details.", + "allOf": [ + { + "$ref": "#/definitions/MacOS" + } + ] }, "win": { - "$ref": "#/definitions/Windows" + "title": "Win", + "description": "Options for Windows. See :class:`Windows` model for details.", + "allOf": [ + { + "$ref": "#/definitions/Windows" + } + ] } }, "additionalProperties": false @@ -667,6 +773,7 @@ "properties": { "name": { "title": "Name", + "description": "The name of the menu item. Can be a dictionary if the name depends on\ninstallation parameters. See :class:`MenuItemNameDict` for details.", "anyOf": [ { "type": "string", @@ -679,10 +786,12 @@ }, "description": { "title": "Description", + "description": "A longer description of the menu item. Shown on popup messages.", "type": "string" }, "command": { "title": "Command", + "description": "Command to run with the menu item, expressed as a\nlist of strings where each string is an argument.", "minItems": 1, "type": "array", "items": { @@ -691,36 +800,48 @@ }, "icon": { "title": "Icon", + "description": "Path to the file representing or containing the icon.", "minLength": 1, "type": "string" }, "precommand": { "title": "Precommand", + "description": "(Simple, preferrably single-line) logic to run before the command is run.\nRuns before the environment is activated, if that applies.", "minLength": 1, "type": "string" }, "precreate": { "title": "Precreate", + "description": "(Simple, preferrably single-line) logic to run before the shortcut is created.", "minLength": 1, "type": "string" }, "working_dir": { "title": "Working Dir", + "description": "Working directory for the running process.\nDefaults to user directory on each platform.", "minLength": 1, "type": "string" }, "activate": { "title": "Activate", + "description": "Whether to activate the target environment before running ``command``.", "default": true, "type": "boolean" }, "terminal": { "title": "Terminal", + "description": "Whether run the program in a terminal/console or not.\nOn Windows, it only has an effect if ``activate`` is true.\nOn MacOS, the application will ignore command-line arguments.", "default": false, "type": "boolean" }, "platforms": { - "$ref": "#/definitions/Platforms" + "title": "Platforms", + "description": "Platform-specific options. Presence of a platform field enables\nmenu items in that platform.\"", + "allOf": [ + { + "$ref": "#/definitions/Platforms" + } + ] } }, "required": [ From f368e155a562f106e22ef2ca0ba070561ca75aec Mon Sep 17 00:00:00 2001 From: jaimergp Date: Sun, 24 Nov 2024 23:53:22 +0100 Subject: [PATCH 2/9] pre-commit --- menuinst/_schema.py | 475 ++++++++++++++++++++++++++------------------ 1 file changed, 283 insertions(+), 192 deletions(-) diff --git a/menuinst/_schema.py b/menuinst/_schema.py index a1d49cce..abc54ac8 100644 --- a/menuinst/_schema.py +++ b/menuinst/_schema.py @@ -57,10 +57,12 @@ class BasePlatformSpecific(BaseModel): name: Optional[Union[constr(min_length=1), MenuItemNameDict]] = Field( None, - description=cleandoc(""" - The name of the menu item. Can be a dictionary if the name depends on - installation parameters. See :class:`MenuItemNameDict` for details. - """), + description=cleandoc( + """ + The name of the menu item. Can be a dictionary if the name depends on + installation parameters. See :class:`MenuItemNameDict` for details. + """ + ), ) description: Optional[str] = Field( None, @@ -72,28 +74,36 @@ class BasePlatformSpecific(BaseModel): ) command: Optional[conlist(str, min_items=1)] = Field( None, - description=cleandoc(""" - Command to run with the menu item, expressed as a - list of strings where each string is an argument. - """), + description=cleandoc( + """ + Command to run with the menu item, expressed as a + list of strings where each string is an argument. + """ + ), ) working_dir: Optional[constr(min_length=1)] = Field( None, - description=cleandoc(""" - Working directory for the running process. - Defaults to user directory on each platform. - """), + description=cleandoc( + """ + Working directory for the running process. + Defaults to user directory on each platform. + """ + ), ) precommand: Optional[constr(min_length=1)] = Field( None, - description=cleandoc(""" - (Simple, preferrably single-line) logic to run before the command is run. - Runs before the env is activated, if that applies. - """), + description=cleandoc( + """ + (Simple, preferrably single-line) logic to run before the command is run. + Runs before the environment is activated, if that applies. + """ + ), ) precreate: Optional[constr(min_length=1)] = Field( None, - description="(Simple, preferrably single-line) logic to run before the shortcut is created.", + description=cleandoc( + """(Simple, preferrably single-line) logic to run before the shortcut is created.""" + ), ) activate: Optional[bool] = Field( None, @@ -101,11 +111,13 @@ class BasePlatformSpecific(BaseModel): ) terminal: Optional[bool] = Field( None, - description=cleandoc(""" - Whether run the program in a terminal/console or not. - On Windows, it only has an effect if ``activate`` is true. - On MacOS, the application will ignore command-line arguments. - """), + description=cleandoc( + """ + Whether run the program in a terminal/console or not. + On Windows, it only has an effect if ``activate`` is true. + On MacOS, the application will ignore command-line arguments. + """ + ), ) @@ -118,18 +130,22 @@ class Windows(BasePlatformSpecific): ) quicklaunch: Optional[bool] = Field( False, - description=cleandoc(""" - DEPRECATED. Whether to create a quick launch icon in addition to the Start Menu item. - """), + description=cleandoc( + """ + DEPRECATED. Whether to create a quick launch icon in addition to the Start Menu item. + """ + ), deprecated=True, ) terminal_profile: constr(min_length=1) = Field( None, - description=cleandoc(""" - Name of the Windows Terminal profile to create. - This name must be unique across multiple installations because - menuinst will overwrite Terminal profiles with the same name. - """), + description=cleandoc( + """ + Name of the Windows Terminal profile to create. + This name must be unique across multiple installations because + menuinst will overwrite Terminal profiles with the same name. + """ + ), ) url_protocols: Optional[List[constr(regex=r"\S+")]] = Field( None, @@ -141,15 +157,17 @@ class Windows(BasePlatformSpecific): ) app_user_model_id: Optional[constr(regex=r"\S+\.\S+", max_length=128)] = Field( None, - description=cleandoc(""" - Identifier used in Windows 7 and above to associate processes, files and windows with a - particular application. If your shortcut produces duplicated icons, you need to define this - field. If not set, it will default to ``Menuinst.``. + description=cleandoc( + """ + Identifier used in Windows 7 and above to associate processes, files and windows with a + particular application. If your shortcut produces duplicated icons, you need to define + this field. If not set, it will default to ``Menuinst.``. - See `AppUserModelID docs - `__ - for more information on the required string format. - """), + See `AppUserModelID docs + `__ + for more information on the required string format. + """ + ), ) @@ -164,24 +182,30 @@ class Linux(BasePlatformSpecific): Categories: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( None, - description=cleandoc(""" - Categories in which the entry should be shown in a menu. - "See 'Registered categories' in the `Menu Spec - `__. - """), + description=cleandoc( + """ + Categories in which the entry should be shown in a menu. + "See 'Registered categories' in the `Menu Spec + `__. + """ + ), ) DBusActivatable: Optional[bool] = Field( None, description=cleandoc( - """A boolean value specifying if D-Bus activation is supported for this application. - """), + """ + A boolean value specifying if D-Bus activation is supported for this application. + """ + ), ) GenericName: Optional[str] = Field( None, - description=cleandoc(""" - Generic name of the application; e.g. if the name is 'conda', - this would be 'Package Manager'. - """), + description=cleandoc( + """ + Generic name of the application; e.g. if the name is 'conda', + this would be 'Package Manager'. + """ + ), ) Hidden: Optional[bool] = Field( None, @@ -189,10 +213,12 @@ class Linux(BasePlatformSpecific): ) Implements: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( None, - description=cleandoc(""" - List of supported interfaces. See 'Interfaces' in `Desktop Entry Spec - `__. - """), + description=cleandoc( + """ + List of supported interfaces. See 'Interfaces' in `Desktop Entry Spec + `__. + """ + ), ) Keywords: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( None, @@ -200,76 +226,96 @@ class Linux(BasePlatformSpecific): ) MimeType: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( None, - description=cleandoc(""" - The MIME type(s) supported by this application. - Note this includes file types and URL protocols. - For URL protocols, use ``x-scheme-handler/your-protocol-here``. - For example, if you want to register ``menuinst:``, you would - include ``x-scheme-handler/menuinst``. - """), + description=cleandoc( + """ + The MIME type(s) supported by this application. + Note this includes file types and URL protocols. + For URL protocols, use ``x-scheme-handler/your-protocol-here``. + For example, if you want to register ``menuinst:``, you would + include ``x-scheme-handler/menuinst``. + """ + ), ) NoDisplay: Optional[bool] = Field( None, - description=cleandoc(""" - Do not show this item in the menu. Useful to associate MIME types - and other registrations, without having an actual clickable item. - Not to be confused with 'Hidden'. - """), + description=cleandoc( + """ + Do not show this item in the menu. Useful to associate MIME types + and other registrations, without having an actual clickable item. + Not to be confused with 'Hidden'. + """ + ), ) NotShowIn: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( None, - description=cleandoc(""" - Desktop environments that should NOT display this item. - It'll check against ``$XDG_CURRENT_DESKTOP``." - """), + description=cleandoc( + """ + Desktop environments that should NOT display this item. + It'll check against ``$XDG_CURRENT_DESKTOP``." + """ + ), ) OnlyShowIn: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( None, - description=cleandoc(""" - Desktop environments that should display this item. - It'll check against ``$XDG_CURRENT_DESKTOP``. - """), + description=cleandoc( + """ + Desktop environments that should display this item. + It'll check against ``$XDG_CURRENT_DESKTOP``. + """ + ), ) PrefersNonDefaultGPU: Optional[bool] = Field( None, - description=cleandoc(""" - Hint that the app prefers to be run on a more powerful discrete GPU if available. - """), + description=cleandoc( + """ + Hint that the app prefers to be run on a more powerful discrete GPU if available. + """ + ), ) SingleMainWindow: Optional[bool] = Field( None, - description=cleandoc(""" - Do not show the 'New Window' option in the app's context menu. - """), + description=cleandoc( + """ + Do not show the 'New Window' option in the app's context menu. + """ + ), ) StartupNotify: Optional[bool] = Field( None, - description=cleandoc(""" - Advanced. See `Startup Notification spec - `__. - """), + description=cleandoc( + """ + Advanced. See `Startup Notification spec + `__. + """ + ), ) StartupWMClass: Optional[str] = Field( None, - description=cleandoc(""" - Advanced. See `Startup Notification spec - `__. - """), + description=cleandoc( + """ + Advanced. See `Startup Notification spec + `__. + """ + ), ) TryExec: Optional[str] = Field( None, - description=cleandoc(""" - Filename or absolute path to an executable file on disk used to - determine if the program is actually installed and can be run. If the test - fails, the shortcut might be ignored / hidden. - """), + description=cleandoc( + """ + Filename or absolute path to an executable file on disk used to + determine if the program is actually installed and can be run. If the test + fails, the shortcut might be ignored / hidden. + """ + ), ) glob_patterns: Optional[Dict[str, constr(regex=r".*\*.*")]] = Field( None, - description=cleandoc(""" - Map of custom MIME types to their corresponding glob patterns (e.g. ``*.txt``). - Only needed if you define custom MIME types in ``MimeType``. - """), + description=cleandoc( + """ + Map of custom MIME types to their corresponding glob patterns (e.g. ``*.txt``). + Only needed if you define custom MIME types in ``MimeType``. + """ + ), ) @@ -318,23 +364,28 @@ class CFBundleDocumentTypesModel(BaseModel): ) LSItemContentTypes: List[str] = Field( ..., - description=cleandoc(""" - List of UTI strings defining a supported file type; e.g. for - PNG files, use 'public.png'. See `UTI Reference - `__ - for more info about the system-defined UTIs. Custom UTIs can be - defined via 'UTExportedTypeDeclarations'. UTIs defined by other - apps (not the system) need to be imported via 'UTImportedTypeDeclarations'. - - See `Fun with UTIs `__ for more info. - """), + description=cleandoc( + """ + List of UTI strings defining a supported file type; e.g. for PNG files, use + 'public.png'. See `UTI Reference + `__ + for more info about the system-defined UTIs. Custom UTIs can be defined via + 'UTExportedTypeDeclarations'. UTIs defined by other apps (not the system) need to + be imported via 'UTImportedTypeDeclarations'. + + See `Fun with UTIs `__ for more + info. + """ + ), ) LSHandlerRank: Literal["Owner", "Default", "Alternate"] = Field( ..., - description=cleandoc(""" - Determines how Launch Services ranks this app among the apps - that declare themselves editors or viewers of files of this type. - """), + description=cleandoc( + """ + Determines how Launch Services ranks this app among the apps + that declare themselves editors or viewers of files of this type. + """ + ), ) class UTTypeDeclarationModel(BaseModel): @@ -365,53 +416,67 @@ class UTTypeDeclarationModel(BaseModel): CFBundleDisplayName: Optional[str] = Field( None, - description=cleandoc(""" - Display name of the bundle, visible to users and used by Siri. If - not provided, 'menuinst' will use the 'name' field. - """), + description=cleandoc( + """ + Display name of the bundle, visible to users and used by Siri. If + not provided, 'menuinst' will use the 'name' field. + """ + ), ) CFBundleIdentifier: Optional[constr(regex=r"^[A-z0-9\-\.]+$")] = Field( None, - description=cleandoc(""" - Unique identifier for the shortcut. Typically uses a reverse-DNS format. - If not provided, 'menuinst' will generate one from the 'name' field. - """), + description=cleandoc( + """ + Unique identifier for the shortcut. Typically uses a reverse-DNS format. + If not provided, 'menuinst' will generate one from the 'name' field. + """ + ), ) CFBundleName: Optional[constr(max_length=16)] = Field( None, - description=cleandoc(""" - Short name of the bundle. May be used if ``CFBundleDisplayName`` is - absent. If not provided, 'menuinst' will generate one from the 'name' field. - """), + description=cleandoc( + """ + Short name of the bundle. May be used if ``CFBundleDisplayName`` is + absent. If not provided, 'menuinst' will generate one from the 'name' field. + """ + ), ) CFBundleSpokenName: Optional[str] = Field( None, - description=cleandoc(""" - Suitable replacement for text-to-speech operations on the app. - For example, 'my app one two three' instead of 'MyApp123'. - """), + description=cleandoc( + """ + Suitable replacement for text-to-speech operations on the app. + For example, 'my app one two three' instead of 'MyApp123'. + """ + ), ) CFBundleVersion: Optional[constr(regex=r"^\S+$")] = Field( None, - description=cleandoc(""" - Build version number for the bundle. In the context of 'menuinst' - this can be used to signal a new version of the menu item for the same - application version. - """), + description=cleandoc( + """ + Build version number for the bundle. In the context of 'menuinst' + this can be used to signal a new version of the menu item for the same + application version. + """ + ), ) CFBundleURLTypes: Optional[List[CFBundleURLTypesModel]] = Field( None, - description=cleandoc(""" - URL types supported by this app. Requires setting `event_handler` too. - Note this feature requires macOS 10.14.4 or above. - """), + description=cleandoc( + """ + URL types supported by this app. Requires setting `event_handler` too. + Note this feature requires macOS 10.14.4 or above. + """ + ), ) CFBundleDocumentTypes: Optional[List[CFBundleDocumentTypesModel]] = Field( None, - description=cleandoc(""" - Document types supported by this app. Requires setting `event_handler` too. - Requires macOS 10.14.4 or above. - """), + description=cleandoc( + """ + Document types supported by this app. Requires setting `event_handler` too. + Requires macOS 10.14.4 or above. + """ + ), ) LSApplicationCategoryType: Optional[constr(regex=r"^public\.app-category\.\S+$")] = Field( None, @@ -427,23 +492,29 @@ class UTTypeDeclarationModel(BaseModel): ) LSMinimumSystemVersion: Optional[constr(regex=r"^\d+\.\d+\.\d+$")] = Field( None, - description=cleandoc(""" - Minimum version of macOS required for this app to run, as ``x.y.z``. - For example, for macOS v10.4 and later, use ``10.4.0``. - """), + description=cleandoc( + """ + Minimum version of macOS required for this app to run, as ``x.y.z``. + For example, for macOS v10.4 and later, use ``10.4.0``. + """ + ), ) LSMultipleInstancesProhibited: Optional[bool] = Field( None, - description=cleandoc(""" - Whether an app is prohibited from running simultaneously in multiple user sessions." - """), + description=cleandoc( + """ + Whether an app is prohibited from running simultaneously in multiple user sessions." + """ + ), ) LSRequiresNativeExecution: Optional[bool] = Field( None, - description=cleandoc(""" - If true, prevent a universal binary from being run under - Rosetta emulation on an Intel-based Mac. - """), + description=cleandoc( + """ + If true, prevent a universal binary from being run under + Rosetta emulation on an Intel-based Mac. + """ + ), ) NSSupportsAutomaticGraphicsSwitching: Optional[bool] = Field( None, @@ -458,28 +529,34 @@ class UTTypeDeclarationModel(BaseModel): ) entitlements: Optional[List[constr(regex=r"[a-z0-9\.\-]+")]] = Field( None, - description=cleandoc(""" - List of permissions to request for the launched application. - See `the entitlements docs `__ - for a full list of possible values. - """), + description=cleandoc( + """ + List of permissions to request for the launched application. See `the entitlements docs + `__ for a full + list of possible values. + """ + ), ) link_in_bundle: Optional[Dict[constr(min_length=1), constr(regex=r"^(?!\/)(?!\.\./).*")]] = ( Field( None, - description=cleandoc(""" - Paths that should be symlinked into the shortcut app bundle. - It takes a mapping of source to destination paths. Destination paths must be - relative. Placeholder ``{{ MENU_ITEM_LOCATION }}`` can be useful. - """), + description=cleandoc( + """ + Paths that should be symlinked into the shortcut app bundle. + It takes a mapping of source to destination paths. Destination paths must be + relative. Placeholder ``{{ MENU_ITEM_LOCATION }}`` can be useful. + """ + ), ) ) event_handler: Optional[constr(min_length=1)] = Field( None, - description=cleandoc(""" - Required shell script logic to handle opened URL payloads. - Note this feature requires macOS 10.14.4 or above. - """), + description=cleandoc( + """ + Required shell script logic to handle opened URL payloads. + Note this feature requires macOS 10.14.4 or above. + """ + ), ) @@ -507,10 +584,12 @@ class MenuItem(BaseModel): name: Union[constr(min_length=1), MenuItemNameDict] = Field( ..., - description=cleandoc(""" - The name of the menu item. Can be a dictionary if the name depends on - installation parameters. See :class:`MenuItemNameDict` for details. - """), + description=cleandoc( + """ + The name of the menu item. Can be a dictionary if the name depends on + installation parameters. See :class:`MenuItemNameDict` for details. + """ + ), ) description: str = Field( ..., @@ -518,10 +597,12 @@ class MenuItem(BaseModel): ) command: conlist(str, min_items=1) = Field( ..., - description=cleandoc(""" - Command to run with the menu item, expressed as a - list of strings where each string is an argument. - """), + description=cleandoc( + """ + Command to run with the menu item, expressed as a + list of strings where each string is an argument. + """ + ), ) icon: Optional[constr(min_length=1)] = Field( None, @@ -529,23 +610,29 @@ class MenuItem(BaseModel): ) precommand: Optional[constr(min_length=1)] = Field( None, - description=cleandoc(""" - (Simple, preferrably single-line) logic to run before the command is run. - Runs before the environment is activated, if that applies. - """), + description=cleandoc( + """ + (Simple, preferrably single-line) logic to run before the command is run. + Runs before the environment is activated, if that applies. + """ + ), ) precreate: Optional[constr(min_length=1)] = Field( None, - description=cleandoc(""" - (Simple, preferrably single-line) logic to run before the shortcut is created. - """), + description=cleandoc( + """ + (Simple, preferrably single-line) logic to run before the shortcut is created. + """ + ), ) working_dir: Optional[constr(min_length=1)] = Field( None, - description=cleandoc(""" - Working directory for the running process. - Defaults to user directory on each platform. - """), + description=cleandoc( + """ + Working directory for the running process. + Defaults to user directory on each platform. + """ + ), ) activate: Optional[bool] = Field( True, @@ -553,17 +640,21 @@ class MenuItem(BaseModel): ) terminal: Optional[bool] = Field( False, - description=cleandoc(""" - Whether run the program in a terminal/console or not. - On Windows, it only has an effect if ``activate`` is true. - On MacOS, the application will ignore command-line arguments. - """), + description=cleandoc( + """ + Whether run the program in a terminal/console or not. + On Windows, it only has an effect if ``activate`` is true. + On MacOS, the application will ignore command-line arguments. + """ + ), ) platforms: Platforms = Field( - description=cleandoc(""" - Platform-specific options. Presence of a platform field enables - menu items in that platform." - """), + description=cleandoc( + """ + Platform-specific options. Presence of a platform field enables + menu items in that platform." + """ + ), ) From 6dd15f03a1ae8ea2a1a47e9600ccb07c80287d8b Mon Sep 17 00:00:00 2001 From: jaimergp Date: Mon, 25 Nov 2024 00:17:02 +0100 Subject: [PATCH 3/9] dump schema --- menuinst/data/menuinst.schema.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/menuinst/data/menuinst.schema.json b/menuinst/data/menuinst.schema.json index 0fbeb1fa..32a6f740 100644 --- a/menuinst/data/menuinst.schema.json +++ b/menuinst/data/menuinst.schema.json @@ -109,7 +109,7 @@ }, "precommand": { "title": "Precommand", - "description": "(Simple, preferrably single-line) logic to run before the command is run.\nRuns before the env is activated, if that applies.", + "description": "(Simple, preferrably single-line) logic to run before the command is run.\nRuns before the environment is activated, if that applies.", "minLength": 1, "type": "string" }, @@ -147,7 +147,7 @@ }, "DBusActivatable": { "title": "Dbusactivatable", - "description": "A boolean value specifying if D-Bus activation is supported for this application.\n ", + "description": "A boolean value specifying if D-Bus activation is supported for this application.", "type": "boolean" }, "GenericName": { @@ -350,7 +350,7 @@ }, "LSItemContentTypes": { "title": "Lsitemcontenttypes", - "description": "List of UTI strings defining a supported file type; e.g. for\nPNG files, use 'public.png'. See `UTI Reference\n`__\nfor more info about the system-defined UTIs. Custom UTIs can be\ndefined via 'UTExportedTypeDeclarations'. UTIs defined by other\napps (not the system) need to be imported via 'UTImportedTypeDeclarations'.\n\nSee `Fun with UTIs `__ for more info.", + "description": "List of UTI strings defining a supported file type; e.g. for PNG files, use\n'public.png'. See `UTI Reference\n`__\nfor more info about the system-defined UTIs. Custom UTIs can be defined via\n'UTExportedTypeDeclarations'. UTIs defined by other apps (not the system) need to\nbe imported via 'UTImportedTypeDeclarations'.\n\nSee `Fun with UTIs `__ for more\ninfo.", "type": "array", "items": { "type": "string" @@ -471,7 +471,7 @@ }, "precommand": { "title": "Precommand", - "description": "(Simple, preferrably single-line) logic to run before the command is run.\nRuns before the env is activated, if that applies.", + "description": "(Simple, preferrably single-line) logic to run before the command is run.\nRuns before the environment is activated, if that applies.", "minLength": 1, "type": "string" }, @@ -593,7 +593,7 @@ }, "entitlements": { "title": "Entitlements", - "description": "List of permissions to request for the launched application.\nSee `the entitlements docs `__\nfor a full list of possible values.", + "description": "List of permissions to request for the launched application. See `the entitlements docs\n`__ for a full\nlist of possible values.", "type": "array", "items": { "type": "string", @@ -664,7 +664,7 @@ }, "precommand": { "title": "Precommand", - "description": "(Simple, preferrably single-line) logic to run before the command is run.\nRuns before the env is activated, if that applies.", + "description": "(Simple, preferrably single-line) logic to run before the command is run.\nRuns before the environment is activated, if that applies.", "minLength": 1, "type": "string" }, @@ -723,7 +723,7 @@ }, "app_user_model_id": { "title": "App User Model Id", - "description": "Identifier used in Windows 7 and above to associate processes, files and windows with a\nparticular application. If your shortcut produces duplicated icons, you need to define this\nfield. If not set, it will default to ``Menuinst.``.\n\nSee `AppUserModelID docs\n`__\nfor more information on the required string format.", + "description": "Identifier used in Windows 7 and above to associate processes, files and windows with a\nparticular application. If your shortcut produces duplicated icons, you need to define\nthis field. If not set, it will default to ``Menuinst.``.\n\nSee `AppUserModelID docs\n`__\nfor more information on the required string format.", "maxLength": 128, "pattern": "\\S+\\.\\S+", "type": "string" From 159eb8f9ce9ad27bab9755f988fd0fa831729583 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Mon, 25 Nov 2024 10:27:55 +0100 Subject: [PATCH 4/9] unnecessary quote --- menuinst/_schema.py | 2 +- menuinst/data/menuinst.schema.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/menuinst/_schema.py b/menuinst/_schema.py index abc54ac8..71004d27 100644 --- a/menuinst/_schema.py +++ b/menuinst/_schema.py @@ -652,7 +652,7 @@ class MenuItem(BaseModel): description=cleandoc( """ Platform-specific options. Presence of a platform field enables - menu items in that platform." + menu items in that platform. """ ), ) diff --git a/menuinst/data/menuinst.schema.json b/menuinst/data/menuinst.schema.json index 32a6f740..7e8f517d 100644 --- a/menuinst/data/menuinst.schema.json +++ b/menuinst/data/menuinst.schema.json @@ -836,7 +836,7 @@ }, "platforms": { "title": "Platforms", - "description": "Platform-specific options. Presence of a platform field enables\nmenu items in that platform.\"", + "description": "Platform-specific options. Presence of a platform field enables\nmenu items in that platform.", "allOf": [ { "$ref": "#/definitions/Platforms" From 7224bac308b81f4de98303cb9d8f48cf127cf01b Mon Sep 17 00:00:00 2001 From: jaimergp Date: Mon, 25 Nov 2024 10:48:19 +0100 Subject: [PATCH 5/9] add news --- news/281-fields | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 news/281-fields diff --git a/news/281-fields b/news/281-fields new file mode 100644 index 00000000..cccbbfa9 --- /dev/null +++ b/news/281-fields @@ -0,0 +1,19 @@ +### Enhancements + +* + +### Bug fixes + +* Make sure the Pydantic field descriptions make it to the generated JSON schema. (#281) + +### Deprecations + +* + +### Docs + +* + +### Other + +* From 7a776eb7e4e90055cf5f95822e27c805b9657180 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Wed, 27 Nov 2024 19:11:02 +0100 Subject: [PATCH 6/9] join contiguous lines --- menuinst/_schema.py | 96 ++++++++++++++++-------------- menuinst/data/menuinst.schema.json | 96 +++++++++++++++--------------- 2 files changed, 99 insertions(+), 93 deletions(-) diff --git a/menuinst/_schema.py b/menuinst/_schema.py index 71004d27..a8015710 100644 --- a/menuinst/_schema.py +++ b/menuinst/_schema.py @@ -6,6 +6,7 @@ # pyright: reportInvalidTypeForm=false, reportCallIssue=false, reportGeneralTypeIssues=false import json +import re from inspect import cleandoc from logging import getLogger from pathlib import Path @@ -24,6 +25,11 @@ log = getLogger(__name__) +def _clean_description(description: str) -> str: + # The regex below only replaces newlines surrounded by non-newlines + return re.sub(r'(?`__. @@ -226,7 +232,7 @@ class Linux(BasePlatformSpecific): ) MimeType: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( None, - description=cleandoc( + description=_clean_description( """ The MIME type(s) supported by this application. Note this includes file types and URL protocols. @@ -238,7 +244,7 @@ class Linux(BasePlatformSpecific): ) NoDisplay: Optional[bool] = Field( None, - description=cleandoc( + description=_clean_description( """ Do not show this item in the menu. Useful to associate MIME types and other registrations, without having an actual clickable item. @@ -248,7 +254,7 @@ class Linux(BasePlatformSpecific): ) NotShowIn: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( None, - description=cleandoc( + description=_clean_description( """ Desktop environments that should NOT display this item. It'll check against ``$XDG_CURRENT_DESKTOP``." @@ -257,7 +263,7 @@ class Linux(BasePlatformSpecific): ) OnlyShowIn: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( None, - description=cleandoc( + description=_clean_description( """ Desktop environments that should display this item. It'll check against ``$XDG_CURRENT_DESKTOP``. @@ -266,7 +272,7 @@ class Linux(BasePlatformSpecific): ) PrefersNonDefaultGPU: Optional[bool] = Field( None, - description=cleandoc( + description=_clean_description( """ Hint that the app prefers to be run on a more powerful discrete GPU if available. """ @@ -274,7 +280,7 @@ class Linux(BasePlatformSpecific): ) SingleMainWindow: Optional[bool] = Field( None, - description=cleandoc( + description=_clean_description( """ Do not show the 'New Window' option in the app's context menu. """ @@ -282,7 +288,7 @@ class Linux(BasePlatformSpecific): ) StartupNotify: Optional[bool] = Field( None, - description=cleandoc( + description=_clean_description( """ Advanced. See `Startup Notification spec `__. @@ -291,7 +297,7 @@ class Linux(BasePlatformSpecific): ) StartupWMClass: Optional[str] = Field( None, - description=cleandoc( + description=_clean_description( """ Advanced. See `Startup Notification spec `__. @@ -300,7 +306,7 @@ class Linux(BasePlatformSpecific): ) TryExec: Optional[str] = Field( None, - description=cleandoc( + description=_clean_description( """ Filename or absolute path to an executable file on disk used to determine if the program is actually installed and can be run. If the test @@ -310,7 +316,7 @@ class Linux(BasePlatformSpecific): ) glob_patterns: Optional[Dict[str, constr(regex=r".*\*.*")]] = Field( None, - description=cleandoc( + description=_clean_description( """ Map of custom MIME types to their corresponding glob patterns (e.g. ``*.txt``). Only needed if you define custom MIME types in ``MimeType``. @@ -364,7 +370,7 @@ class CFBundleDocumentTypesModel(BaseModel): ) LSItemContentTypes: List[str] = Field( ..., - description=cleandoc( + description=_clean_description( """ List of UTI strings defining a supported file type; e.g. for PNG files, use 'public.png'. See `UTI Reference @@ -380,7 +386,7 @@ class CFBundleDocumentTypesModel(BaseModel): ) LSHandlerRank: Literal["Owner", "Default", "Alternate"] = Field( ..., - description=cleandoc( + description=_clean_description( """ Determines how Launch Services ranks this app among the apps that declare themselves editors or viewers of files of this type. @@ -416,7 +422,7 @@ class UTTypeDeclarationModel(BaseModel): CFBundleDisplayName: Optional[str] = Field( None, - description=cleandoc( + description=_clean_description( """ Display name of the bundle, visible to users and used by Siri. If not provided, 'menuinst' will use the 'name' field. @@ -425,7 +431,7 @@ class UTTypeDeclarationModel(BaseModel): ) CFBundleIdentifier: Optional[constr(regex=r"^[A-z0-9\-\.]+$")] = Field( None, - description=cleandoc( + description=_clean_description( """ Unique identifier for the shortcut. Typically uses a reverse-DNS format. If not provided, 'menuinst' will generate one from the 'name' field. @@ -434,7 +440,7 @@ class UTTypeDeclarationModel(BaseModel): ) CFBundleName: Optional[constr(max_length=16)] = Field( None, - description=cleandoc( + description=_clean_description( """ Short name of the bundle. May be used if ``CFBundleDisplayName`` is absent. If not provided, 'menuinst' will generate one from the 'name' field. @@ -443,7 +449,7 @@ class UTTypeDeclarationModel(BaseModel): ) CFBundleSpokenName: Optional[str] = Field( None, - description=cleandoc( + description=_clean_description( """ Suitable replacement for text-to-speech operations on the app. For example, 'my app one two three' instead of 'MyApp123'. @@ -452,7 +458,7 @@ class UTTypeDeclarationModel(BaseModel): ) CFBundleVersion: Optional[constr(regex=r"^\S+$")] = Field( None, - description=cleandoc( + description=_clean_description( """ Build version number for the bundle. In the context of 'menuinst' this can be used to signal a new version of the menu item for the same @@ -462,7 +468,7 @@ class UTTypeDeclarationModel(BaseModel): ) CFBundleURLTypes: Optional[List[CFBundleURLTypesModel]] = Field( None, - description=cleandoc( + description=_clean_description( """ URL types supported by this app. Requires setting `event_handler` too. Note this feature requires macOS 10.14.4 or above. @@ -471,7 +477,7 @@ class UTTypeDeclarationModel(BaseModel): ) CFBundleDocumentTypes: Optional[List[CFBundleDocumentTypesModel]] = Field( None, - description=cleandoc( + description=_clean_description( """ Document types supported by this app. Requires setting `event_handler` too. Requires macOS 10.14.4 or above. @@ -492,7 +498,7 @@ class UTTypeDeclarationModel(BaseModel): ) LSMinimumSystemVersion: Optional[constr(regex=r"^\d+\.\d+\.\d+$")] = Field( None, - description=cleandoc( + description=_clean_description( """ Minimum version of macOS required for this app to run, as ``x.y.z``. For example, for macOS v10.4 and later, use ``10.4.0``. @@ -501,7 +507,7 @@ class UTTypeDeclarationModel(BaseModel): ) LSMultipleInstancesProhibited: Optional[bool] = Field( None, - description=cleandoc( + description=_clean_description( """ Whether an app is prohibited from running simultaneously in multiple user sessions." """ @@ -509,7 +515,7 @@ class UTTypeDeclarationModel(BaseModel): ) LSRequiresNativeExecution: Optional[bool] = Field( None, - description=cleandoc( + description=_clean_description( """ If true, prevent a universal binary from being run under Rosetta emulation on an Intel-based Mac. @@ -529,7 +535,7 @@ class UTTypeDeclarationModel(BaseModel): ) entitlements: Optional[List[constr(regex=r"[a-z0-9\.\-]+")]] = Field( None, - description=cleandoc( + description=_clean_description( """ List of permissions to request for the launched application. See `the entitlements docs `__ for a full @@ -540,7 +546,7 @@ class UTTypeDeclarationModel(BaseModel): link_in_bundle: Optional[Dict[constr(min_length=1), constr(regex=r"^(?!\/)(?!\.\./).*")]] = ( Field( None, - description=cleandoc( + description=_clean_description( """ Paths that should be symlinked into the shortcut app bundle. It takes a mapping of source to destination paths. Destination paths must be @@ -551,7 +557,7 @@ class UTTypeDeclarationModel(BaseModel): ) event_handler: Optional[constr(min_length=1)] = Field( None, - description=cleandoc( + description=_clean_description( """ Required shell script logic to handle opened URL payloads. Note this feature requires macOS 10.14.4 or above. @@ -584,7 +590,7 @@ class MenuItem(BaseModel): name: Union[constr(min_length=1), MenuItemNameDict] = Field( ..., - description=cleandoc( + description=_clean_description( """ The name of the menu item. Can be a dictionary if the name depends on installation parameters. See :class:`MenuItemNameDict` for details. @@ -597,7 +603,7 @@ class MenuItem(BaseModel): ) command: conlist(str, min_items=1) = Field( ..., - description=cleandoc( + description=_clean_description( """ Command to run with the menu item, expressed as a list of strings where each string is an argument. @@ -610,7 +616,7 @@ class MenuItem(BaseModel): ) precommand: Optional[constr(min_length=1)] = Field( None, - description=cleandoc( + description=_clean_description( """ (Simple, preferrably single-line) logic to run before the command is run. Runs before the environment is activated, if that applies. @@ -619,7 +625,7 @@ class MenuItem(BaseModel): ) precreate: Optional[constr(min_length=1)] = Field( None, - description=cleandoc( + description=_clean_description( """ (Simple, preferrably single-line) logic to run before the shortcut is created. """ @@ -627,7 +633,7 @@ class MenuItem(BaseModel): ) working_dir: Optional[constr(min_length=1)] = Field( None, - description=cleandoc( + description=_clean_description( """ Working directory for the running process. Defaults to user directory on each platform. @@ -640,7 +646,7 @@ class MenuItem(BaseModel): ) terminal: Optional[bool] = Field( False, - description=cleandoc( + description=_clean_description( """ Whether run the program in a terminal/console or not. On Windows, it only has an effect if ``activate`` is true. @@ -649,7 +655,7 @@ class MenuItem(BaseModel): ), ) platforms: Platforms = Field( - description=cleandoc( + description=_clean_description( """ Platform-specific options. Presence of a platform field enables menu items in that platform. diff --git a/menuinst/data/menuinst.schema.json b/menuinst/data/menuinst.schema.json index 7e8f517d..321dc3e8 100644 --- a/menuinst/data/menuinst.schema.json +++ b/menuinst/data/menuinst.schema.json @@ -70,7 +70,7 @@ "properties": { "name": { "title": "Name", - "description": "The name of the menu item. Can be a dictionary if the name depends on\ninstallation parameters. See :class:`MenuItemNameDict` for details.", + "description": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See :class:`MenuItemNameDict` for details.", "anyOf": [ { "type": "string", @@ -94,7 +94,7 @@ }, "command": { "title": "Command", - "description": "Command to run with the menu item, expressed as a\nlist of strings where each string is an argument.", + "description": "Command to run with the menu item, expressed as a list of strings where each string is an argument.", "minItems": 1, "type": "array", "items": { @@ -103,13 +103,13 @@ }, "working_dir": { "title": "Working Dir", - "description": "Working directory for the running process.\nDefaults to user directory on each platform.", + "description": "Working directory for the running process. Defaults to user directory on each platform.", "minLength": 1, "type": "string" }, "precommand": { "title": "Precommand", - "description": "(Simple, preferrably single-line) logic to run before the command is run.\nRuns before the environment is activated, if that applies.", + "description": "(Simple, preferrably single-line) logic to run before the command is run. Runs before the environment is activated, if that applies.", "minLength": 1, "type": "string" }, @@ -126,12 +126,12 @@ }, "terminal": { "title": "Terminal", - "description": "Whether run the program in a terminal/console or not.\nOn Windows, it only has an effect if ``activate`` is true.\nOn MacOS, the application will ignore command-line arguments.", + "description": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if ``activate`` is true. On MacOS, the application will ignore command-line arguments.", "type": "boolean" }, "Categories": { "title": "Categories", - "description": "Categories in which the entry should be shown in a menu.\n\"See 'Registered categories' in the `Menu Spec\n`__.", + "description": "Categories in which the entry should be shown in a menu. \"See 'Registered categories' in the `Menu Spec `__.", "anyOf": [ { "type": "array", @@ -152,7 +152,7 @@ }, "GenericName": { "title": "Genericname", - "description": "Generic name of the application; e.g. if the name is 'conda',\nthis would be 'Package Manager'.", + "description": "Generic name of the application; e.g. if the name is 'conda', this would be 'Package Manager'.", "type": "string" }, "Hidden": { @@ -162,7 +162,7 @@ }, "Implements": { "title": "Implements", - "description": "List of supported interfaces. See 'Interfaces' in `Desktop Entry Spec\n`__.", + "description": "List of supported interfaces. See 'Interfaces' in `Desktop Entry Spec `__.", "anyOf": [ { "type": "array", @@ -194,7 +194,7 @@ }, "MimeType": { "title": "Mimetype", - "description": "The MIME type(s) supported by this application.\nNote this includes file types and URL protocols.\nFor URL protocols, use ``x-scheme-handler/your-protocol-here``.\nFor example, if you want to register ``menuinst:``, you would\ninclude ``x-scheme-handler/menuinst``.", + "description": "The MIME type(s) supported by this application. Note this includes file types and URL protocols. For URL protocols, use ``x-scheme-handler/your-protocol-here``. For example, if you want to register ``menuinst:``, you would include ``x-scheme-handler/menuinst``.", "anyOf": [ { "type": "array", @@ -210,12 +210,12 @@ }, "NoDisplay": { "title": "Nodisplay", - "description": "Do not show this item in the menu. Useful to associate MIME types\nand other registrations, without having an actual clickable item.\nNot to be confused with 'Hidden'.", + "description": "Do not show this item in the menu. Useful to associate MIME types and other registrations, without having an actual clickable item. Not to be confused with 'Hidden'.", "type": "boolean" }, "NotShowIn": { "title": "Notshowin", - "description": "Desktop environments that should NOT display this item.\nIt'll check against ``$XDG_CURRENT_DESKTOP``.\"", + "description": "Desktop environments that should NOT display this item. It'll check against ``$XDG_CURRENT_DESKTOP``.\"", "anyOf": [ { "type": "array", @@ -231,7 +231,7 @@ }, "OnlyShowIn": { "title": "Onlyshowin", - "description": "Desktop environments that should display this item.\nIt'll check against ``$XDG_CURRENT_DESKTOP``.", + "description": "Desktop environments that should display this item. It'll check against ``$XDG_CURRENT_DESKTOP``.", "anyOf": [ { "type": "array", @@ -257,22 +257,22 @@ }, "StartupNotify": { "title": "Startupnotify", - "description": "Advanced. See `Startup Notification spec\n`__.", + "description": "Advanced. See `Startup Notification spec `__.", "type": "boolean" }, "StartupWMClass": { "title": "Startupwmclass", - "description": "Advanced. See `Startup Notification spec\n`__.", + "description": "Advanced. See `Startup Notification spec `__.", "type": "string" }, "TryExec": { "title": "Tryexec", - "description": "Filename or absolute path to an executable file on disk used to\ndetermine if the program is actually installed and can be run. If the test\nfails, the shortcut might be ignored / hidden.", + "description": "Filename or absolute path to an executable file on disk used to determine if the program is actually installed and can be run. If the test fails, the shortcut might be ignored / hidden.", "type": "string" }, "glob_patterns": { "title": "Glob Patterns", - "description": "Map of custom MIME types to their corresponding glob patterns (e.g. ``*.txt``).\nOnly needed if you define custom MIME types in ``MimeType``.", + "description": "Map of custom MIME types to their corresponding glob patterns (e.g. ``*.txt``). Only needed if you define custom MIME types in ``MimeType``.", "type": "object", "additionalProperties": { "type": "string", @@ -350,7 +350,7 @@ }, "LSItemContentTypes": { "title": "Lsitemcontenttypes", - "description": "List of UTI strings defining a supported file type; e.g. for PNG files, use\n'public.png'. See `UTI Reference\n`__\nfor more info about the system-defined UTIs. Custom UTIs can be defined via\n'UTExportedTypeDeclarations'. UTIs defined by other apps (not the system) need to\nbe imported via 'UTImportedTypeDeclarations'.\n\nSee `Fun with UTIs `__ for more\ninfo.", + "description": "List of UTI strings defining a supported file type; e.g. for PNG files, use 'public.png'. See `UTI Reference `__ for more info about the system-defined UTIs. Custom UTIs can be defined via 'UTExportedTypeDeclarations'. UTIs defined by other apps (not the system) need to be imported via 'UTImportedTypeDeclarations'.\n\nSee `Fun with UTIs `__ for more info.", "type": "array", "items": { "type": "string" @@ -358,7 +358,7 @@ }, "LSHandlerRank": { "title": "Lshandlerrank", - "description": "Determines how Launch Services ranks this app among the apps\nthat declare themselves editors or viewers of files of this type.", + "description": "Determines how Launch Services ranks this app among the apps that declare themselves editors or viewers of files of this type.", "enum": [ "Owner", "Default", @@ -432,7 +432,7 @@ "properties": { "name": { "title": "Name", - "description": "The name of the menu item. Can be a dictionary if the name depends on\ninstallation parameters. See :class:`MenuItemNameDict` for details.", + "description": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See :class:`MenuItemNameDict` for details.", "anyOf": [ { "type": "string", @@ -456,7 +456,7 @@ }, "command": { "title": "Command", - "description": "Command to run with the menu item, expressed as a\nlist of strings where each string is an argument.", + "description": "Command to run with the menu item, expressed as a list of strings where each string is an argument.", "minItems": 1, "type": "array", "items": { @@ -465,13 +465,13 @@ }, "working_dir": { "title": "Working Dir", - "description": "Working directory for the running process.\nDefaults to user directory on each platform.", + "description": "Working directory for the running process. Defaults to user directory on each platform.", "minLength": 1, "type": "string" }, "precommand": { "title": "Precommand", - "description": "(Simple, preferrably single-line) logic to run before the command is run.\nRuns before the environment is activated, if that applies.", + "description": "(Simple, preferrably single-line) logic to run before the command is run. Runs before the environment is activated, if that applies.", "minLength": 1, "type": "string" }, @@ -488,40 +488,40 @@ }, "terminal": { "title": "Terminal", - "description": "Whether run the program in a terminal/console or not.\nOn Windows, it only has an effect if ``activate`` is true.\nOn MacOS, the application will ignore command-line arguments.", + "description": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if ``activate`` is true. On MacOS, the application will ignore command-line arguments.", "type": "boolean" }, "CFBundleDisplayName": { "title": "Cfbundledisplayname", - "description": "Display name of the bundle, visible to users and used by Siri. If\nnot provided, 'menuinst' will use the 'name' field.", + "description": "Display name of the bundle, visible to users and used by Siri. If not provided, 'menuinst' will use the 'name' field.", "type": "string" }, "CFBundleIdentifier": { "title": "Cfbundleidentifier", - "description": "Unique identifier for the shortcut. Typically uses a reverse-DNS format.\nIf not provided, 'menuinst' will generate one from the 'name' field.", + "description": "Unique identifier for the shortcut. Typically uses a reverse-DNS format. If not provided, 'menuinst' will generate one from the 'name' field.", "pattern": "^[A-z0-9\\-\\.]+$", "type": "string" }, "CFBundleName": { "title": "Cfbundlename", - "description": "Short name of the bundle. May be used if ``CFBundleDisplayName`` is\nabsent. If not provided, 'menuinst' will generate one from the 'name' field.", + "description": "Short name of the bundle. May be used if ``CFBundleDisplayName`` is absent. If not provided, 'menuinst' will generate one from the 'name' field.", "maxLength": 16, "type": "string" }, "CFBundleSpokenName": { "title": "Cfbundlespokenname", - "description": "Suitable replacement for text-to-speech operations on the app.\nFor example, 'my app one two three' instead of 'MyApp123'.", + "description": "Suitable replacement for text-to-speech operations on the app. For example, 'my app one two three' instead of 'MyApp123'.", "type": "string" }, "CFBundleVersion": { "title": "Cfbundleversion", - "description": "Build version number for the bundle. In the context of 'menuinst'\nthis can be used to signal a new version of the menu item for the same\napplication version.", + "description": "Build version number for the bundle. In the context of 'menuinst' this can be used to signal a new version of the menu item for the same application version.", "pattern": "^\\S+$", "type": "string" }, "CFBundleURLTypes": { "title": "Cfbundleurltypes", - "description": "URL types supported by this app. Requires setting `event_handler` too.\nNote this feature requires macOS 10.14.4 or above.", + "description": "URL types supported by this app. Requires setting `event_handler` too. Note this feature requires macOS 10.14.4 or above.", "type": "array", "items": { "$ref": "#/definitions/CFBundleURLTypesModel" @@ -529,7 +529,7 @@ }, "CFBundleDocumentTypes": { "title": "Cfbundledocumenttypes", - "description": "Document types supported by this app. Requires setting `event_handler` too.\nRequires macOS 10.14.4 or above.", + "description": "Document types supported by this app. Requires setting `event_handler` too. Requires macOS 10.14.4 or above.", "type": "array", "items": { "$ref": "#/definitions/CFBundleDocumentTypesModel" @@ -556,7 +556,7 @@ }, "LSMinimumSystemVersion": { "title": "Lsminimumsystemversion", - "description": "Minimum version of macOS required for this app to run, as ``x.y.z``.\nFor example, for macOS v10.4 and later, use ``10.4.0``.", + "description": "Minimum version of macOS required for this app to run, as ``x.y.z``. For example, for macOS v10.4 and later, use ``10.4.0``.", "pattern": "^\\d+\\.\\d+\\.\\d+$", "type": "string" }, @@ -567,7 +567,7 @@ }, "LSRequiresNativeExecution": { "title": "Lsrequiresnativeexecution", - "description": "If true, prevent a universal binary from being run under\nRosetta emulation on an Intel-based Mac.", + "description": "If true, prevent a universal binary from being run under Rosetta emulation on an Intel-based Mac.", "type": "boolean" }, "NSSupportsAutomaticGraphicsSwitching": { @@ -593,7 +593,7 @@ }, "entitlements": { "title": "Entitlements", - "description": "List of permissions to request for the launched application. See `the entitlements docs\n`__ for a full\nlist of possible values.", + "description": "List of permissions to request for the launched application. See `the entitlements docs `__ for a full list of possible values.", "type": "array", "items": { "type": "string", @@ -602,7 +602,7 @@ }, "link_in_bundle": { "title": "Link In Bundle", - "description": "Paths that should be symlinked into the shortcut app bundle.\nIt takes a mapping of source to destination paths. Destination paths must be\nrelative. Placeholder ``{{ MENU_ITEM_LOCATION }}`` can be useful.", + "description": "Paths that should be symlinked into the shortcut app bundle. It takes a mapping of source to destination paths. Destination paths must be relative. Placeholder ``{{ MENU_ITEM_LOCATION }}`` can be useful.", "type": "object", "additionalProperties": { "type": "string", @@ -611,7 +611,7 @@ }, "event_handler": { "title": "Event Handler", - "description": "Required shell script logic to handle opened URL payloads.\nNote this feature requires macOS 10.14.4 or above.", + "description": "Required shell script logic to handle opened URL payloads. Note this feature requires macOS 10.14.4 or above.", "minLength": 1, "type": "string" } @@ -625,7 +625,7 @@ "properties": { "name": { "title": "Name", - "description": "The name of the menu item. Can be a dictionary if the name depends on\ninstallation parameters. See :class:`MenuItemNameDict` for details.", + "description": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See :class:`MenuItemNameDict` for details.", "anyOf": [ { "type": "string", @@ -649,7 +649,7 @@ }, "command": { "title": "Command", - "description": "Command to run with the menu item, expressed as a\nlist of strings where each string is an argument.", + "description": "Command to run with the menu item, expressed as a list of strings where each string is an argument.", "minItems": 1, "type": "array", "items": { @@ -658,13 +658,13 @@ }, "working_dir": { "title": "Working Dir", - "description": "Working directory for the running process.\nDefaults to user directory on each platform.", + "description": "Working directory for the running process. Defaults to user directory on each platform.", "minLength": 1, "type": "string" }, "precommand": { "title": "Precommand", - "description": "(Simple, preferrably single-line) logic to run before the command is run.\nRuns before the environment is activated, if that applies.", + "description": "(Simple, preferrably single-line) logic to run before the command is run. Runs before the environment is activated, if that applies.", "minLength": 1, "type": "string" }, @@ -681,7 +681,7 @@ }, "terminal": { "title": "Terminal", - "description": "Whether run the program in a terminal/console or not.\nOn Windows, it only has an effect if ``activate`` is true.\nOn MacOS, the application will ignore command-line arguments.", + "description": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if ``activate`` is true. On MacOS, the application will ignore command-line arguments.", "type": "boolean" }, "desktop": { @@ -699,7 +699,7 @@ }, "terminal_profile": { "title": "Terminal Profile", - "description": "Name of the Windows Terminal profile to create.\nThis name must be unique across multiple installations because\nmenuinst will overwrite Terminal profiles with the same name.", + "description": "Name of the Windows Terminal profile to create. This name must be unique across multiple installations because menuinst will overwrite Terminal profiles with the same name.", "minLength": 1, "type": "string" }, @@ -723,7 +723,7 @@ }, "app_user_model_id": { "title": "App User Model Id", - "description": "Identifier used in Windows 7 and above to associate processes, files and windows with a\nparticular application. If your shortcut produces duplicated icons, you need to define\nthis field. If not set, it will default to ``Menuinst.``.\n\nSee `AppUserModelID docs\n`__\nfor more information on the required string format.", + "description": "Identifier used in Windows 7 and above to associate processes, files and windows with a particular application. If your shortcut produces duplicated icons, you need to define this field. If not set, it will default to ``Menuinst.``.\n\nSee `AppUserModelID docs `__ for more information on the required string format.", "maxLength": 128, "pattern": "\\S+\\.\\S+", "type": "string" @@ -773,7 +773,7 @@ "properties": { "name": { "title": "Name", - "description": "The name of the menu item. Can be a dictionary if the name depends on\ninstallation parameters. See :class:`MenuItemNameDict` for details.", + "description": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See :class:`MenuItemNameDict` for details.", "anyOf": [ { "type": "string", @@ -791,7 +791,7 @@ }, "command": { "title": "Command", - "description": "Command to run with the menu item, expressed as a\nlist of strings where each string is an argument.", + "description": "Command to run with the menu item, expressed as a list of strings where each string is an argument.", "minItems": 1, "type": "array", "items": { @@ -806,7 +806,7 @@ }, "precommand": { "title": "Precommand", - "description": "(Simple, preferrably single-line) logic to run before the command is run.\nRuns before the environment is activated, if that applies.", + "description": "(Simple, preferrably single-line) logic to run before the command is run. Runs before the environment is activated, if that applies.", "minLength": 1, "type": "string" }, @@ -818,7 +818,7 @@ }, "working_dir": { "title": "Working Dir", - "description": "Working directory for the running process.\nDefaults to user directory on each platform.", + "description": "Working directory for the running process. Defaults to user directory on each platform.", "minLength": 1, "type": "string" }, @@ -830,13 +830,13 @@ }, "terminal": { "title": "Terminal", - "description": "Whether run the program in a terminal/console or not.\nOn Windows, it only has an effect if ``activate`` is true.\nOn MacOS, the application will ignore command-line arguments.", + "description": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if ``activate`` is true. On MacOS, the application will ignore command-line arguments.", "default": false, "type": "boolean" }, "platforms": { "title": "Platforms", - "description": "Platform-specific options. Presence of a platform field enables\nmenu items in that platform.", + "description": "Platform-specific options. Presence of a platform field enables menu items in that platform.", "allOf": [ { "$ref": "#/definitions/Platforms" From a728f34a9731acb0b349f75da2a42ddbceeb1d25 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Wed, 27 Nov 2024 20:27:28 +0100 Subject: [PATCH 7/9] use markdown for field descriptions --- docs/environment.yml | 1 + docs/source/conf.py | 18 ++ menuinst/_schema.py | 281 ++++++++++++++++------------- menuinst/data/menuinst.schema.json | 197 +++++++++++++++----- 4 files changed, 324 insertions(+), 173 deletions(-) diff --git a/docs/environment.yml b/docs/environment.yml index 5d5d6f4e..eb57724a 100644 --- a/docs/environment.yml +++ b/docs/environment.yml @@ -13,6 +13,7 @@ dependencies: - cffi=1.15.1 - charset-normalizer=2.1.1 - colorama=0.4.6 + - commonmark=0.9.1 - cryptography=38.0.3 - docutils=0.19 - idna=3.4 diff --git a/docs/source/conf.py b/docs/source/conf.py index c669677f..d930ba3f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -6,8 +6,11 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html import json +import os from pathlib import Path +import commonmark + # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information @@ -117,3 +120,18 @@ sitemap_locales = [None] # We're hard-coding stable here since that's what we want Google to point to. sitemap_url_scheme = "{link}" + + +# Custom hooks +os.environ["SPHINX_RUNNING"] = "1" + +def docstring(app, what, name, obj, options, lines): + """Transform MD to RST for autodoc""" + md = '\n'.join(lines) + ast = commonmark.Parser().parse(md) + rst = commonmark.ReStructuredTextRenderer().render(ast) + lines.clear() + lines += rst.splitlines() + +def setup(app): + app.connect('autodoc-process-docstring', docstring) diff --git a/menuinst/_schema.py b/menuinst/_schema.py index a8015710..ce80e69d 100644 --- a/menuinst/_schema.py +++ b/menuinst/_schema.py @@ -6,6 +6,7 @@ # pyright: reportInvalidTypeForm=false, reportCallIssue=false, reportGeneralTypeIssues=false import json +import os import re from inspect import cleandoc from logging import getLogger @@ -15,11 +16,11 @@ try: from pydantic.v1 import BaseModel as _BaseModel - from pydantic.v1 import Field, conlist, constr + from pydantic.v1 import Field as _Field, conlist, constr except ImportError: # pydantic v1 from pydantic import BaseModel as _BaseModel - from pydantic import Field, conlist, constr + from pydantic import Field as _Field, conlist, constr log = getLogger(__name__) @@ -27,13 +28,31 @@ def _clean_description(description: str) -> str: # The regex below only replaces newlines surrounded by non-newlines - return re.sub(r'(?``. + this field. If not set, it will default to `Menuinst.`. - See `AppUserModelID docs - `__ + See [AppUserModelID docs]( + https://learn.microsoft.com/en-us/windows/win32/shell/appids#how-to-form-an-application-defined-appusermodelid) for more information on the required string format. """ ), @@ -181,24 +200,24 @@ class Linux(BasePlatformSpecific): """ Linux-specific instructions. - Check the `Desktop entry specification - `__ + Check the [Desktop entry specification]( + https://specifications.freedesktop.org/desktop-entry-spec/latest/recognized-keys.html) for more details. """ Categories: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( None, - description=_clean_description( + description=( """ Categories in which the entry should be shown in a menu. - "See 'Registered categories' in the `Menu Spec - `__. + See 'Registered categories' in the [Menu Spec]( + http://www.freedesktop.org/Standards/menu-spec). """ ), ) DBusActivatable: Optional[bool] = Field( None, - description=_clean_description( + description=( """ A boolean value specifying if D-Bus activation is supported for this application. """ @@ -206,7 +225,7 @@ class Linux(BasePlatformSpecific): ) GenericName: Optional[str] = Field( None, - description=_clean_description( + description=( """ Generic name of the application; e.g. if the name is 'conda', this would be 'Package Manager'. @@ -215,36 +234,36 @@ class Linux(BasePlatformSpecific): ) Hidden: Optional[bool] = Field( None, - description="Disable shortcut, signaling a missing resource.", + description=("Disable shortcut, signaling a missing resource."), ) Implements: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( None, - description=_clean_description( + description=( """ - List of supported interfaces. See 'Interfaces' in `Desktop Entry Spec - `__. + List of supported interfaces. See 'Interfaces' in [Desktop Entry Spec]( + https://specifications.freedesktop.org/desktop-entry-spec/latest/interfaces.html). """ ), ) Keywords: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( None, - description="Additional terms to describe this shortcut to aid in searching.", + description=("Additional terms to describe this shortcut to aid in searching."), ) MimeType: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( None, - description=_clean_description( + description=( """ The MIME type(s) supported by this application. Note this includes file types and URL protocols. - For URL protocols, use ``x-scheme-handler/your-protocol-here``. - For example, if you want to register ``menuinst:``, you would - include ``x-scheme-handler/menuinst``. + For URL protocols, use `x-scheme-handler/your-protocol-here`. + For example, if you want to register `menuinst:`, you would + include `x-scheme-handler/menuinst`. """ ), ) NoDisplay: Optional[bool] = Field( None, - description=_clean_description( + description=( """ Do not show this item in the menu. Useful to associate MIME types and other registrations, without having an actual clickable item. @@ -254,25 +273,25 @@ class Linux(BasePlatformSpecific): ) NotShowIn: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( None, - description=_clean_description( + description=( """ Desktop environments that should NOT display this item. - It'll check against ``$XDG_CURRENT_DESKTOP``." + It'll check against `$XDG_CURRENT_DESKTOP`. """ ), ) OnlyShowIn: Optional[Union[List[str], constr(regex=r"^.+;$")]] = Field( None, - description=_clean_description( + description=( """ Desktop environments that should display this item. - It'll check against ``$XDG_CURRENT_DESKTOP``. + It'll check against `$XDG_CURRENT_DESKTOP`. """ ), ) PrefersNonDefaultGPU: Optional[bool] = Field( None, - description=_clean_description( + description=( """ Hint that the app prefers to be run on a more powerful discrete GPU if available. """ @@ -280,7 +299,7 @@ class Linux(BasePlatformSpecific): ) SingleMainWindow: Optional[bool] = Field( None, - description=_clean_description( + description=( """ Do not show the 'New Window' option in the app's context menu. """ @@ -288,25 +307,25 @@ class Linux(BasePlatformSpecific): ) StartupNotify: Optional[bool] = Field( None, - description=_clean_description( + description=( """ - Advanced. See `Startup Notification spec - `__. + Advanced. See [Startup Notification spec]( + https://www.freedesktop.org/wiki/Specifications/startup-notification-spec/). """ ), ) StartupWMClass: Optional[str] = Field( None, - description=_clean_description( + description=( """ - Advanced. See `Startup Notification spec - `__. + Advanced. See [Startup Notification spec]( + https://www.freedesktop.org/wiki/Specifications/startup-notification-spec/). """ ), ) TryExec: Optional[str] = Field( None, - description=_clean_description( + description=( """ Filename or absolute path to an executable file on disk used to determine if the program is actually installed and can be run. If the test @@ -316,10 +335,10 @@ class Linux(BasePlatformSpecific): ) glob_patterns: Optional[Dict[str, constr(regex=r".*\*.*")]] = Field( None, - description=_clean_description( + description=( """ - Map of custom MIME types to their corresponding glob patterns (e.g. ``*.txt``). - Only needed if you define custom MIME types in ``MimeType``. + Map of custom MIME types to their corresponding glob patterns (e.g. `*.txt`). + Only needed if you define custom MIME types in `MimeType`. """ ), ) @@ -329,9 +348,9 @@ class MacOS(BasePlatformSpecific): """ Mac-specific instructions. Check these URLs for more info: - - ``CF*`` keys: see `Core Foundation Keys `__ - - ``LS*`` keys: see `Launch Services Keys `__ - - ``entitlements``: see `Entitlements documentation `__ + - `CF*` keys: see [Core Foundation Keys](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html) + - `LS*` keys: see [Launch Services Keys](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html) + - `entitlements`: see [Entitlements documentation](https://developer.apple.com/documentation/bundleresources/entitlements) """ class CFBundleURLTypesModel(BaseModel): @@ -339,19 +358,19 @@ class CFBundleURLTypesModel(BaseModel): CFBundleTypeRole: Optional[Literal["Editor", "Viewer", "Shell", "None"]] = Field( None, - description="This key specifies the app's role with respect to the URL.", + description=("This key specifies the app's role with respect to the URL."), ) CFBundleURLSchemes: List[str] = Field( ..., - description="URL schemes / protocols handled by this type (e.g. 'mailto').", + description=("URL schemes / protocols handled by this type (e.g. 'mailto')."), ) CFBundleURLName: Optional[str] = Field( None, - description="Abstract name for this URL type. Uniqueness recommended.", + description=("Abstract name for this URL type. Uniqueness recommended."), ) CFBundleURLIconFile: Optional[str] = Field( None, - description="Name of the icon image file (minus the .icns extension).", + description=("Name of the icon image file (minus the .icns extension)."), ) class CFBundleDocumentTypesModel(BaseModel): @@ -359,34 +378,34 @@ class CFBundleDocumentTypesModel(BaseModel): CFBundleTypeIconFile: Optional[str] = Field( None, - description="Name of the icon image file (minus the .icns extension).", + description=("Name of the icon image file (minus the .icns extension)."), ) CFBundleTypeName: str = Field( ..., - description="Abstract name for this document type. Uniqueness recommended.", + description=("Abstract name for this document type. Uniqueness recommended."), ) CFBundleTypeRole: Optional[Literal["Editor", "Viewer", "Shell", "None"]] = Field( - None, description="This key specifies the app's role with respect to the type." + None, description=("This key specifies the app's role with respect to the type.") ) LSItemContentTypes: List[str] = Field( ..., - description=_clean_description( + description=( """ List of UTI strings defining a supported file type; e.g. for PNG files, use - 'public.png'. See `UTI Reference - `__ + 'public.png'. See [UTI Reference]( + https://developer.apple.com/library/archive/documentation/Miscellaneous/Reference/UTIRef/Articles/System-DeclaredUniformTypeIdentifiers.html) for more info about the system-defined UTIs. Custom UTIs can be defined via 'UTExportedTypeDeclarations'. UTIs defined by other apps (not the system) need to be imported via 'UTImportedTypeDeclarations'. - See `Fun with UTIs `__ for more + See [Fun with UTIs](https://www.cocoanetics.com/2012/09/fun-with-uti/) for more info. """ ), ) LSHandlerRank: Literal["Owner", "Default", "Alternate"] = Field( ..., - description=_clean_description( + description=( """ Determines how Launch Services ranks this app among the apps that declare themselves editors or viewers of files of this type. @@ -397,32 +416,32 @@ class CFBundleDocumentTypesModel(BaseModel): class UTTypeDeclarationModel(BaseModel): UTTypeConformsTo: List[str] = Field( ..., - description="The Uniform Type Identifier types that this type conforms to.", + description=("The Uniform Type Identifier types that this type conforms to."), ) UTTypeDescription: Optional[str] = Field( None, - description="A description for this type.", + description=("A description for this type."), ) UTTypeIconFile: Optional[str] = Field( None, - description="The bundle icon resource to associate with this type.", + description=("The bundle icon resource to associate with this type."), ) UTTypeIdentifier: str = Field( ..., - description="The Uniform Type Identifier to assign to this type.", + description=("The Uniform Type Identifier to assign to this type."), ) UTTypeReferenceURL: Optional[str] = Field( None, - description="The webpage for a reference document that describes this type.", + description=("The webpage for a reference document that describes this type."), ) UTTypeTagSpecification: Dict[str, List[str]] = Field( ..., - description="A dictionary defining one or more equivalent type identifiers.", + description=("A dictionary defining one or more equivalent type identifiers."), ) CFBundleDisplayName: Optional[str] = Field( None, - description=_clean_description( + description=( """ Display name of the bundle, visible to users and used by Siri. If not provided, 'menuinst' will use the 'name' field. @@ -431,7 +450,7 @@ class UTTypeDeclarationModel(BaseModel): ) CFBundleIdentifier: Optional[constr(regex=r"^[A-z0-9\-\.]+$")] = Field( None, - description=_clean_description( + description=( """ Unique identifier for the shortcut. Typically uses a reverse-DNS format. If not provided, 'menuinst' will generate one from the 'name' field. @@ -440,16 +459,16 @@ class UTTypeDeclarationModel(BaseModel): ) CFBundleName: Optional[constr(max_length=16)] = Field( None, - description=_clean_description( + description=( """ - Short name of the bundle. May be used if ``CFBundleDisplayName`` is + Short name of the bundle. May be used if `CFBundleDisplayName` is absent. If not provided, 'menuinst' will generate one from the 'name' field. """ ), ) CFBundleSpokenName: Optional[str] = Field( None, - description=_clean_description( + description=( """ Suitable replacement for text-to-speech operations on the app. For example, 'my app one two three' instead of 'MyApp123'. @@ -458,7 +477,7 @@ class UTTypeDeclarationModel(BaseModel): ) CFBundleVersion: Optional[constr(regex=r"^\S+$")] = Field( None, - description=_clean_description( + description=( """ Build version number for the bundle. In the context of 'menuinst' this can be used to signal a new version of the menu item for the same @@ -468,7 +487,7 @@ class UTTypeDeclarationModel(BaseModel): ) CFBundleURLTypes: Optional[List[CFBundleURLTypesModel]] = Field( None, - description=_clean_description( + description=( """ URL types supported by this app. Requires setting `event_handler` too. Note this feature requires macOS 10.14.4 or above. @@ -477,7 +496,7 @@ class UTTypeDeclarationModel(BaseModel): ) CFBundleDocumentTypes: Optional[List[CFBundleDocumentTypesModel]] = Field( None, - description=_clean_description( + description=( """ Document types supported by this app. Requires setting `event_handler` too. Requires macOS 10.14.4 or above. @@ -486,36 +505,36 @@ class UTTypeDeclarationModel(BaseModel): ) LSApplicationCategoryType: Optional[constr(regex=r"^public\.app-category\.\S+$")] = Field( None, - description="The App Store uses this string to determine the appropriate categorization.", + description=("The App Store uses this string to determine the appropriate categorization."), ) LSBackgroundOnly: Optional[bool] = Field( None, - description="Specifies whether this app runs only in the background.", + description=("Specifies whether this app runs only in the background."), ) LSEnvironment: Optional[Dict[str, str]] = Field( None, - description="List of key-value pairs used to define environment variables.", + description=("List of key-value pairs used to define environment variables."), ) LSMinimumSystemVersion: Optional[constr(regex=r"^\d+\.\d+\.\d+$")] = Field( None, - description=_clean_description( + description=( """ - Minimum version of macOS required for this app to run, as ``x.y.z``. - For example, for macOS v10.4 and later, use ``10.4.0``. + Minimum version of macOS required for this app to run, as `x.y.z`. + For example, for macOS v10.4 and later, use `10.4.0`. """ ), ) LSMultipleInstancesProhibited: Optional[bool] = Field( None, - description=_clean_description( + description=( """ - Whether an app is prohibited from running simultaneously in multiple user sessions." + Whether an app is prohibited from running simultaneously in multiple user sessions. """ ), ) LSRequiresNativeExecution: Optional[bool] = Field( None, - description=_clean_description( + description=( """ If true, prevent a universal binary from being run under Rosetta emulation on an Intel-based Mac. @@ -524,21 +543,23 @@ class UTTypeDeclarationModel(BaseModel): ) NSSupportsAutomaticGraphicsSwitching: Optional[bool] = Field( None, - description="If true, allows an OpenGL app to utilize the integrated GPU.", + description=("If true, allows an OpenGL app to utilize the integrated GPU."), ) UTExportedTypeDeclarations: Optional[List[UTTypeDeclarationModel]] = Field( - None, description="The uniform type identifiers owned and exported by the app." + None, description=("The uniform type identifiers owned and exported by the app."), ) UTImportedTypeDeclarations: Optional[List[UTTypeDeclarationModel]] = Field( None, - description="The uniform type identifiers inherently supported, but not owned, by the app.", + description=( + "The uniform type identifiers inherently supported, but not owned, by the app." + ), ) entitlements: Optional[List[constr(regex=r"[a-z0-9\.\-]+")]] = Field( None, - description=_clean_description( + description=( """ - List of permissions to request for the launched application. See `the entitlements docs - `__ for a full + List of permissions to request for the launched application. See [the entitlements docs]( + https://developer.apple.com/documentation/bundleresources/entitlements) for a full list of possible values. """ ), @@ -546,18 +567,18 @@ class UTTypeDeclarationModel(BaseModel): link_in_bundle: Optional[Dict[constr(min_length=1), constr(regex=r"^(?!\/)(?!\.\./).*")]] = ( Field( None, - description=_clean_description( + description=( """ Paths that should be symlinked into the shortcut app bundle. It takes a mapping of source to destination paths. Destination paths must be - relative. Placeholder ``{{ MENU_ITEM_LOCATION }}`` can be useful. + relative. Placeholder `{{ MENU_ITEM_LOCATION }}` can be useful. """ ), ) ) event_handler: Optional[constr(min_length=1)] = Field( None, - description=_clean_description( + description=( """ Required shell script logic to handle opened URL payloads. Note this feature requires macOS 10.14.4 or above. @@ -570,18 +591,18 @@ class Platforms(BaseModel): """ Platform specific options. - Note each of these fields supports the same keys as the top-level :class:`MenuItem` - (sans ``platforms`` itself), in case overrides are needed. + Note each of these fields supports the same keys as the top-level `MenuItem` + (sans `platforms` itself), in case overrides are needed. """ linux: Optional[Linux] = Field( - description="Options for Linux. See :class:`Linux` model for details." + description=("Options for Linux. See `Linux` model for details."), ) osx: Optional[MacOS] = Field( - description="Options for macOS. See :class:`MacOS` model for details." + description=("Options for macOS. See `MacOS` model for details."), ) win: Optional[Windows] = Field( - description="Options for Windows. See :class:`Windows` model for details." + description=("Options for Windows. See `Windows` model for details."), ) @@ -590,20 +611,20 @@ class MenuItem(BaseModel): name: Union[constr(min_length=1), MenuItemNameDict] = Field( ..., - description=_clean_description( + description=( """ The name of the menu item. Can be a dictionary if the name depends on - installation parameters. See :class:`MenuItemNameDict` for details. + installation parameters. See `MenuItemNameDict` for details. """ ), ) description: str = Field( ..., - description="A longer description of the menu item. Shown on popup messages.", + description=("A longer description of the menu item. Shown on popup messages."), ) command: conlist(str, min_items=1) = Field( ..., - description=_clean_description( + description=( """ Command to run with the menu item, expressed as a list of strings where each string is an argument. @@ -612,11 +633,11 @@ class MenuItem(BaseModel): ) icon: Optional[constr(min_length=1)] = Field( None, - description="Path to the file representing or containing the icon.", + description=("Path to the file representing or containing the icon."), ) precommand: Optional[constr(min_length=1)] = Field( None, - description=_clean_description( + description=( """ (Simple, preferrably single-line) logic to run before the command is run. Runs before the environment is activated, if that applies. @@ -625,7 +646,7 @@ class MenuItem(BaseModel): ) precreate: Optional[constr(min_length=1)] = Field( None, - description=_clean_description( + description=( """ (Simple, preferrably single-line) logic to run before the shortcut is created. """ @@ -633,7 +654,7 @@ class MenuItem(BaseModel): ) working_dir: Optional[constr(min_length=1)] = Field( None, - description=_clean_description( + description=( """ Working directory for the running process. Defaults to user directory on each platform. @@ -642,20 +663,20 @@ class MenuItem(BaseModel): ) activate: Optional[bool] = Field( True, - description="Whether to activate the target environment before running ``command``.", + description=("Whether to activate the target environment before running `command`."), ) terminal: Optional[bool] = Field( False, - description=_clean_description( + description=( """ Whether run the program in a terminal/console or not. - On Windows, it only has an effect if ``activate`` is true. + On Windows, it only has an effect if `activate` is true. On MacOS, the application will ignore command-line arguments. """ ), ) platforms: Platforms = Field( - description=_clean_description( + description=( """ Platform-specific options. Presence of a platform field enables menu items in that platform. @@ -665,25 +686,25 @@ class MenuItem(BaseModel): class MenuInstSchema(BaseModel): - "Metadata required to create menu items across operating systems with ``menuinst``." + "Metadata required to create menu items across operating systems with `menuinst`." id_: Literal["https://schemas.conda.io/menuinst-1.schema.json"] = Field( ..., - description="Version of the menuinst schema.", + description=("Version of the menuinst schema."), alias="$id", ) schema_: Literal["https://json-schema.org/draft-07/schema"] = Field( ..., - description="Standard of the JSON schema we adhere to.", + description=("Standard of the JSON schema we adhere to."), alias="$schema", ) menu_name: constr(min_length=1) = Field( ..., - description="Name for the category containing the items specified in ``menu_items``.", + description=("Name for the category containing the items specified in `menu_items`."), ) menu_items: conlist(MenuItem, min_items=1) = Field( ..., - description="List of menu entries to create across main desktop systems.", + description=("List of menu entries to create across main desktop systems."), ) diff --git a/menuinst/data/menuinst.schema.json b/menuinst/data/menuinst.schema.json index 321dc3e8..09ac7931 100644 --- a/menuinst/data/menuinst.schema.json +++ b/menuinst/data/menuinst.schema.json @@ -1,11 +1,12 @@ { "title": "MenuInstSchema", - "description": "Metadata required to create menu items across operating systems with ``menuinst``.", + "description": "Metadata required to create menu items across operating systems with `menuinst`.", "type": "object", "properties": { "$id": { "title": "$Id", "description": "Version of the menuinst schema.", + "markdownDescription": "Version of the menuinst schema.", "enum": [ "https://schemas.conda.io/menuinst-1.schema.json" ], @@ -14,6 +15,7 @@ "$schema": { "title": "$Schema", "description": "Standard of the JSON schema we adhere to.", + "markdownDescription": "Standard of the JSON schema we adhere to.", "enum": [ "https://json-schema.org/draft-07/schema" ], @@ -21,13 +23,15 @@ }, "menu_name": { "title": "Menu Name", - "description": "Name for the category containing the items specified in ``menu_items``.", + "description": "Name for the category containing the items specified in `menu_items`.", + "markdownDescription": "Name for the category containing the items specified in `menu_items`.", "minLength": 1, "type": "string" }, "menu_items": { "title": "Menu Items", "description": "List of menu entries to create across main desktop systems.", + "markdownDescription": "List of menu entries to create across main desktop systems.", "minItems": 1, "type": "array", "items": { @@ -42,6 +46,7 @@ "menu_items" ], "additionalProperties": false, + "markdownDescription": "Metadata required to create menu items across operating systems with `menuinst`.", "definitions": { "MenuItemNameDict": { "title": "MenuItemNameDict", @@ -51,26 +56,30 @@ "target_environment_is_base": { "title": "Target Environment Is Base", "description": "Name when target environment is the base environment.", + "markdownDescription": "Name when target environment is the base environment.", "minLength": 1, "type": "string" }, "target_environment_is_not_base": { "title": "Target Environment Is Not Base", "description": "Name when target environment is not the base environment.", + "markdownDescription": "Name when target environment is not the base environment.", "minLength": 1, "type": "string" } }, - "additionalProperties": false + "additionalProperties": false, + "markdownDescription": "Variable menu item name.\nUse this dictionary if the menu item name depends on installation parameters\nsuch as the target environment." }, "Linux": { "title": "Linux", - "description": "Linux-specific instructions.\n\nCheck the `Desktop entry specification\n`__\nfor more details.", + "description": "Linux-specific instructions.\n\nCheck the [Desktop entry specification](\nhttps://specifications.freedesktop.org/desktop-entry-spec/latest/recognized-keys.html)\nfor more details.", "type": "object", "properties": { "name": { "title": "Name", - "description": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See :class:`MenuItemNameDict` for details.", + "description": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See `MenuItemNameDict` for details.", + "markdownDescription": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See `MenuItemNameDict` for details.", "anyOf": [ { "type": "string", @@ -84,17 +93,20 @@ "description": { "title": "Description", "description": "A longer description of the menu item. Shown on popup messages.", + "markdownDescription": "A longer description of the menu item. Shown on popup messages.", "type": "string" }, "icon": { "title": "Icon", "description": "Path to the file representing or containing the icon.", + "markdownDescription": "Path to the file representing or containing the icon.", "minLength": 1, "type": "string" }, "command": { "title": "Command", "description": "Command to run with the menu item, expressed as a list of strings where each string is an argument.", + "markdownDescription": "Command to run with the menu item, expressed as a list of strings where each string is an argument.", "minItems": 1, "type": "array", "items": { @@ -104,34 +116,40 @@ "working_dir": { "title": "Working Dir", "description": "Working directory for the running process. Defaults to user directory on each platform.", + "markdownDescription": "Working directory for the running process. Defaults to user directory on each platform.", "minLength": 1, "type": "string" }, "precommand": { "title": "Precommand", "description": "(Simple, preferrably single-line) logic to run before the command is run. Runs before the environment is activated, if that applies.", + "markdownDescription": "(Simple, preferrably single-line) logic to run before the command is run. Runs before the environment is activated, if that applies.", "minLength": 1, "type": "string" }, "precreate": { "title": "Precreate", "description": "(Simple, preferrably single-line) logic to run before the shortcut is created.", + "markdownDescription": "(Simple, preferrably single-line) logic to run before the shortcut is created.", "minLength": 1, "type": "string" }, "activate": { "title": "Activate", - "description": "Whether to activate the target environment before running ``command``.", + "description": "Whether to activate the target environment before running `command`.", + "markdownDescription": "Whether to activate the target environment before running `command`.", "type": "boolean" }, "terminal": { "title": "Terminal", - "description": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if ``activate`` is true. On MacOS, the application will ignore command-line arguments.", + "description": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if `activate` is true. On MacOS, the application will ignore command-line arguments.", + "markdownDescription": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if `activate` is true. On MacOS, the application will ignore command-line arguments.", "type": "boolean" }, "Categories": { "title": "Categories", - "description": "Categories in which the entry should be shown in a menu. \"See 'Registered categories' in the `Menu Spec `__.", + "description": "Categories in which the entry should be shown in a menu. See 'Registered categories' in the [Menu Spec]( http://www.freedesktop.org/Standards/menu-spec).", + "markdownDescription": "Categories in which the entry should be shown in a menu. See 'Registered categories' in the [Menu Spec]( http://www.freedesktop.org/Standards/menu-spec).", "anyOf": [ { "type": "array", @@ -148,21 +166,25 @@ "DBusActivatable": { "title": "Dbusactivatable", "description": "A boolean value specifying if D-Bus activation is supported for this application.", + "markdownDescription": "A boolean value specifying if D-Bus activation is supported for this application.", "type": "boolean" }, "GenericName": { "title": "Genericname", "description": "Generic name of the application; e.g. if the name is 'conda', this would be 'Package Manager'.", + "markdownDescription": "Generic name of the application; e.g. if the name is 'conda', this would be 'Package Manager'.", "type": "string" }, "Hidden": { "title": "Hidden", "description": "Disable shortcut, signaling a missing resource.", + "markdownDescription": "Disable shortcut, signaling a missing resource.", "type": "boolean" }, "Implements": { "title": "Implements", - "description": "List of supported interfaces. See 'Interfaces' in `Desktop Entry Spec `__.", + "description": "List of supported interfaces. See 'Interfaces' in [Desktop Entry Spec]( https://specifications.freedesktop.org/desktop-entry-spec/latest/interfaces.html).", + "markdownDescription": "List of supported interfaces. See 'Interfaces' in [Desktop Entry Spec]( https://specifications.freedesktop.org/desktop-entry-spec/latest/interfaces.html).", "anyOf": [ { "type": "array", @@ -179,6 +201,7 @@ "Keywords": { "title": "Keywords", "description": "Additional terms to describe this shortcut to aid in searching.", + "markdownDescription": "Additional terms to describe this shortcut to aid in searching.", "anyOf": [ { "type": "array", @@ -194,7 +217,8 @@ }, "MimeType": { "title": "Mimetype", - "description": "The MIME type(s) supported by this application. Note this includes file types and URL protocols. For URL protocols, use ``x-scheme-handler/your-protocol-here``. For example, if you want to register ``menuinst:``, you would include ``x-scheme-handler/menuinst``.", + "description": "The MIME type(s) supported by this application. Note this includes file types and URL protocols. For URL protocols, use `x-scheme-handler/your-protocol-here`. For example, if you want to register `menuinst:`, you would include `x-scheme-handler/menuinst`.", + "markdownDescription": "The MIME type(s) supported by this application. Note this includes file types and URL protocols. For URL protocols, use `x-scheme-handler/your-protocol-here`. For example, if you want to register `menuinst:`, you would include `x-scheme-handler/menuinst`.", "anyOf": [ { "type": "array", @@ -211,11 +235,13 @@ "NoDisplay": { "title": "Nodisplay", "description": "Do not show this item in the menu. Useful to associate MIME types and other registrations, without having an actual clickable item. Not to be confused with 'Hidden'.", + "markdownDescription": "Do not show this item in the menu. Useful to associate MIME types and other registrations, without having an actual clickable item. Not to be confused with 'Hidden'.", "type": "boolean" }, "NotShowIn": { "title": "Notshowin", - "description": "Desktop environments that should NOT display this item. It'll check against ``$XDG_CURRENT_DESKTOP``.\"", + "description": "Desktop environments that should NOT display this item. It'll check against `$XDG_CURRENT_DESKTOP`.", + "markdownDescription": "Desktop environments that should NOT display this item. It'll check against `$XDG_CURRENT_DESKTOP`.", "anyOf": [ { "type": "array", @@ -231,7 +257,8 @@ }, "OnlyShowIn": { "title": "Onlyshowin", - "description": "Desktop environments that should display this item. It'll check against ``$XDG_CURRENT_DESKTOP``.", + "description": "Desktop environments that should display this item. It'll check against `$XDG_CURRENT_DESKTOP`.", + "markdownDescription": "Desktop environments that should display this item. It'll check against `$XDG_CURRENT_DESKTOP`.", "anyOf": [ { "type": "array", @@ -248,31 +275,37 @@ "PrefersNonDefaultGPU": { "title": "Prefersnondefaultgpu", "description": "Hint that the app prefers to be run on a more powerful discrete GPU if available.", + "markdownDescription": "Hint that the app prefers to be run on a more powerful discrete GPU if available.", "type": "boolean" }, "SingleMainWindow": { "title": "Singlemainwindow", "description": "Do not show the 'New Window' option in the app's context menu.", + "markdownDescription": "Do not show the 'New Window' option in the app's context menu.", "type": "boolean" }, "StartupNotify": { "title": "Startupnotify", - "description": "Advanced. See `Startup Notification spec `__.", + "description": "Advanced. See [Startup Notification spec]( https://www.freedesktop.org/wiki/Specifications/startup-notification-spec/).", + "markdownDescription": "Advanced. See [Startup Notification spec]( https://www.freedesktop.org/wiki/Specifications/startup-notification-spec/).", "type": "boolean" }, "StartupWMClass": { "title": "Startupwmclass", - "description": "Advanced. See `Startup Notification spec `__.", + "description": "Advanced. See [Startup Notification spec]( https://www.freedesktop.org/wiki/Specifications/startup-notification-spec/).", + "markdownDescription": "Advanced. See [Startup Notification spec]( https://www.freedesktop.org/wiki/Specifications/startup-notification-spec/).", "type": "string" }, "TryExec": { "title": "Tryexec", "description": "Filename or absolute path to an executable file on disk used to determine if the program is actually installed and can be run. If the test fails, the shortcut might be ignored / hidden.", + "markdownDescription": "Filename or absolute path to an executable file on disk used to determine if the program is actually installed and can be run. If the test fails, the shortcut might be ignored / hidden.", "type": "string" }, "glob_patterns": { "title": "Glob Patterns", - "description": "Map of custom MIME types to their corresponding glob patterns (e.g. ``*.txt``). Only needed if you define custom MIME types in ``MimeType``.", + "description": "Map of custom MIME types to their corresponding glob patterns (e.g. `*.txt`). Only needed if you define custom MIME types in `MimeType`.", + "markdownDescription": "Map of custom MIME types to their corresponding glob patterns (e.g. `*.txt`). Only needed if you define custom MIME types in `MimeType`.", "type": "object", "additionalProperties": { "type": "string", @@ -280,7 +313,8 @@ } } }, - "additionalProperties": false + "additionalProperties": false, + "markdownDescription": "Linux-specific instructions.\n\nCheck the [Desktop entry specification](\nhttps://specifications.freedesktop.org/desktop-entry-spec/latest/recognized-keys.html)\nfor more details." }, "CFBundleURLTypesModel": { "title": "CFBundleURLTypesModel", @@ -290,6 +324,7 @@ "CFBundleTypeRole": { "title": "Cfbundletyperole", "description": "This key specifies the app's role with respect to the URL.", + "markdownDescription": "This key specifies the app's role with respect to the URL.", "enum": [ "Editor", "Viewer", @@ -301,6 +336,7 @@ "CFBundleURLSchemes": { "title": "Cfbundleurlschemes", "description": "URL schemes / protocols handled by this type (e.g. 'mailto').", + "markdownDescription": "URL schemes / protocols handled by this type (e.g. 'mailto').", "type": "array", "items": { "type": "string" @@ -309,18 +345,21 @@ "CFBundleURLName": { "title": "Cfbundleurlname", "description": "Abstract name for this URL type. Uniqueness recommended.", + "markdownDescription": "Abstract name for this URL type. Uniqueness recommended.", "type": "string" }, "CFBundleURLIconFile": { "title": "Cfbundleurliconfile", "description": "Name of the icon image file (minus the .icns extension).", + "markdownDescription": "Name of the icon image file (minus the .icns extension).", "type": "string" } }, "required": [ "CFBundleURLSchemes" ], - "additionalProperties": false + "additionalProperties": false, + "markdownDescription": "Describes a URL scheme associated with the app." }, "CFBundleDocumentTypesModel": { "title": "CFBundleDocumentTypesModel", @@ -330,16 +369,19 @@ "CFBundleTypeIconFile": { "title": "Cfbundletypeiconfile", "description": "Name of the icon image file (minus the .icns extension).", + "markdownDescription": "Name of the icon image file (minus the .icns extension).", "type": "string" }, "CFBundleTypeName": { "title": "Cfbundletypename", "description": "Abstract name for this document type. Uniqueness recommended.", + "markdownDescription": "Abstract name for this document type. Uniqueness recommended.", "type": "string" }, "CFBundleTypeRole": { "title": "Cfbundletyperole", "description": "This key specifies the app's role with respect to the type.", + "markdownDescription": "This key specifies the app's role with respect to the type.", "enum": [ "Editor", "Viewer", @@ -350,7 +392,8 @@ }, "LSItemContentTypes": { "title": "Lsitemcontenttypes", - "description": "List of UTI strings defining a supported file type; e.g. for PNG files, use 'public.png'. See `UTI Reference `__ for more info about the system-defined UTIs. Custom UTIs can be defined via 'UTExportedTypeDeclarations'. UTIs defined by other apps (not the system) need to be imported via 'UTImportedTypeDeclarations'.\n\nSee `Fun with UTIs `__ for more info.", + "description": "List of UTI strings defining a supported file type; e.g. for PNG files, use 'public.png'. See [UTI Reference]( https://developer.apple.com/library/archive/documentation/Miscellaneous/Reference/UTIRef/Articles/System-DeclaredUniformTypeIdentifiers.html) for more info about the system-defined UTIs. Custom UTIs can be defined via 'UTExportedTypeDeclarations'. UTIs defined by other apps (not the system) need to be imported via 'UTImportedTypeDeclarations'.\n\nSee [Fun with UTIs](https://www.cocoanetics.com/2012/09/fun-with-uti/) for more info.", + "markdownDescription": "List of UTI strings defining a supported file type; e.g. for PNG files, use 'public.png'. See [UTI Reference]( https://developer.apple.com/library/archive/documentation/Miscellaneous/Reference/UTIRef/Articles/System-DeclaredUniformTypeIdentifiers.html) for more info about the system-defined UTIs. Custom UTIs can be defined via 'UTExportedTypeDeclarations'. UTIs defined by other apps (not the system) need to be imported via 'UTImportedTypeDeclarations'.\n\nSee [Fun with UTIs](https://www.cocoanetics.com/2012/09/fun-with-uti/) for more info.", "type": "array", "items": { "type": "string" @@ -359,6 +402,7 @@ "LSHandlerRank": { "title": "Lshandlerrank", "description": "Determines how Launch Services ranks this app among the apps that declare themselves editors or viewers of files of this type.", + "markdownDescription": "Determines how Launch Services ranks this app among the apps that declare themselves editors or viewers of files of this type.", "enum": [ "Owner", "Default", @@ -372,7 +416,8 @@ "LSItemContentTypes", "LSHandlerRank" ], - "additionalProperties": false + "additionalProperties": false, + "markdownDescription": "Describes a document type associated with the app." }, "UTTypeDeclarationModel": { "title": "UTTypeDeclarationModel", @@ -381,6 +426,7 @@ "UTTypeConformsTo": { "title": "Uttypeconformsto", "description": "The Uniform Type Identifier types that this type conforms to.", + "markdownDescription": "The Uniform Type Identifier types that this type conforms to.", "type": "array", "items": { "type": "string" @@ -389,26 +435,31 @@ "UTTypeDescription": { "title": "Uttypedescription", "description": "A description for this type.", + "markdownDescription": "A description for this type.", "type": "string" }, "UTTypeIconFile": { "title": "Uttypeiconfile", "description": "The bundle icon resource to associate with this type.", + "markdownDescription": "The bundle icon resource to associate with this type.", "type": "string" }, "UTTypeIdentifier": { "title": "Uttypeidentifier", "description": "The Uniform Type Identifier to assign to this type.", + "markdownDescription": "The Uniform Type Identifier to assign to this type.", "type": "string" }, "UTTypeReferenceURL": { "title": "Uttypereferenceurl", "description": "The webpage for a reference document that describes this type.", + "markdownDescription": "The webpage for a reference document that describes this type.", "type": "string" }, "UTTypeTagSpecification": { "title": "Uttypetagspecification", "description": "A dictionary defining one or more equivalent type identifiers.", + "markdownDescription": "A dictionary defining one or more equivalent type identifiers.", "type": "object", "additionalProperties": { "type": "array", @@ -427,12 +478,13 @@ }, "MacOS": { "title": "MacOS", - "description": "Mac-specific instructions. Check these URLs for more info:\n\n- ``CF*`` keys: see `Core Foundation Keys `__\n- ``LS*`` keys: see `Launch Services Keys `__\n- ``entitlements``: see `Entitlements documentation `__", + "description": "Mac-specific instructions. Check these URLs for more info:\n\n- `CF*` keys: see [Core Foundation Keys](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html)\n- `LS*` keys: see [Launch Services Keys](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html)\n- `entitlements`: see [Entitlements documentation](https://developer.apple.com/documentation/bundleresources/entitlements)", "type": "object", "properties": { "name": { "title": "Name", - "description": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See :class:`MenuItemNameDict` for details.", + "description": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See `MenuItemNameDict` for details.", + "markdownDescription": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See `MenuItemNameDict` for details.", "anyOf": [ { "type": "string", @@ -446,17 +498,20 @@ "description": { "title": "Description", "description": "A longer description of the menu item. Shown on popup messages.", + "markdownDescription": "A longer description of the menu item. Shown on popup messages.", "type": "string" }, "icon": { "title": "Icon", "description": "Path to the file representing or containing the icon.", + "markdownDescription": "Path to the file representing or containing the icon.", "minLength": 1, "type": "string" }, "command": { "title": "Command", "description": "Command to run with the menu item, expressed as a list of strings where each string is an argument.", + "markdownDescription": "Command to run with the menu item, expressed as a list of strings where each string is an argument.", "minItems": 1, "type": "array", "items": { @@ -466,62 +521,73 @@ "working_dir": { "title": "Working Dir", "description": "Working directory for the running process. Defaults to user directory on each platform.", + "markdownDescription": "Working directory for the running process. Defaults to user directory on each platform.", "minLength": 1, "type": "string" }, "precommand": { "title": "Precommand", "description": "(Simple, preferrably single-line) logic to run before the command is run. Runs before the environment is activated, if that applies.", + "markdownDescription": "(Simple, preferrably single-line) logic to run before the command is run. Runs before the environment is activated, if that applies.", "minLength": 1, "type": "string" }, "precreate": { "title": "Precreate", "description": "(Simple, preferrably single-line) logic to run before the shortcut is created.", + "markdownDescription": "(Simple, preferrably single-line) logic to run before the shortcut is created.", "minLength": 1, "type": "string" }, "activate": { "title": "Activate", - "description": "Whether to activate the target environment before running ``command``.", + "description": "Whether to activate the target environment before running `command`.", + "markdownDescription": "Whether to activate the target environment before running `command`.", "type": "boolean" }, "terminal": { "title": "Terminal", - "description": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if ``activate`` is true. On MacOS, the application will ignore command-line arguments.", + "description": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if `activate` is true. On MacOS, the application will ignore command-line arguments.", + "markdownDescription": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if `activate` is true. On MacOS, the application will ignore command-line arguments.", "type": "boolean" }, "CFBundleDisplayName": { "title": "Cfbundledisplayname", "description": "Display name of the bundle, visible to users and used by Siri. If not provided, 'menuinst' will use the 'name' field.", + "markdownDescription": "Display name of the bundle, visible to users and used by Siri. If not provided, 'menuinst' will use the 'name' field.", "type": "string" }, "CFBundleIdentifier": { "title": "Cfbundleidentifier", "description": "Unique identifier for the shortcut. Typically uses a reverse-DNS format. If not provided, 'menuinst' will generate one from the 'name' field.", + "markdownDescription": "Unique identifier for the shortcut. Typically uses a reverse-DNS format. If not provided, 'menuinst' will generate one from the 'name' field.", "pattern": "^[A-z0-9\\-\\.]+$", "type": "string" }, "CFBundleName": { "title": "Cfbundlename", - "description": "Short name of the bundle. May be used if ``CFBundleDisplayName`` is absent. If not provided, 'menuinst' will generate one from the 'name' field.", + "description": "Short name of the bundle. May be used if `CFBundleDisplayName` is absent. If not provided, 'menuinst' will generate one from the 'name' field.", + "markdownDescription": "Short name of the bundle. May be used if `CFBundleDisplayName` is absent. If not provided, 'menuinst' will generate one from the 'name' field.", "maxLength": 16, "type": "string" }, "CFBundleSpokenName": { "title": "Cfbundlespokenname", "description": "Suitable replacement for text-to-speech operations on the app. For example, 'my app one two three' instead of 'MyApp123'.", + "markdownDescription": "Suitable replacement for text-to-speech operations on the app. For example, 'my app one two three' instead of 'MyApp123'.", "type": "string" }, "CFBundleVersion": { "title": "Cfbundleversion", "description": "Build version number for the bundle. In the context of 'menuinst' this can be used to signal a new version of the menu item for the same application version.", + "markdownDescription": "Build version number for the bundle. In the context of 'menuinst' this can be used to signal a new version of the menu item for the same application version.", "pattern": "^\\S+$", "type": "string" }, "CFBundleURLTypes": { "title": "Cfbundleurltypes", "description": "URL types supported by this app. Requires setting `event_handler` too. Note this feature requires macOS 10.14.4 or above.", + "markdownDescription": "URL types supported by this app. Requires setting `event_handler` too. Note this feature requires macOS 10.14.4 or above.", "type": "array", "items": { "$ref": "#/definitions/CFBundleURLTypesModel" @@ -530,6 +596,7 @@ "CFBundleDocumentTypes": { "title": "Cfbundledocumenttypes", "description": "Document types supported by this app. Requires setting `event_handler` too. Requires macOS 10.14.4 or above.", + "markdownDescription": "Document types supported by this app. Requires setting `event_handler` too. Requires macOS 10.14.4 or above.", "type": "array", "items": { "$ref": "#/definitions/CFBundleDocumentTypesModel" @@ -538,17 +605,20 @@ "LSApplicationCategoryType": { "title": "Lsapplicationcategorytype", "description": "The App Store uses this string to determine the appropriate categorization.", + "markdownDescription": "The App Store uses this string to determine the appropriate categorization.", "pattern": "^public\\.app-category\\.\\S+$", "type": "string" }, "LSBackgroundOnly": { "title": "Lsbackgroundonly", "description": "Specifies whether this app runs only in the background.", + "markdownDescription": "Specifies whether this app runs only in the background.", "type": "boolean" }, "LSEnvironment": { "title": "Lsenvironment", "description": "List of key-value pairs used to define environment variables.", + "markdownDescription": "List of key-value pairs used to define environment variables.", "type": "object", "additionalProperties": { "type": "string" @@ -556,28 +626,33 @@ }, "LSMinimumSystemVersion": { "title": "Lsminimumsystemversion", - "description": "Minimum version of macOS required for this app to run, as ``x.y.z``. For example, for macOS v10.4 and later, use ``10.4.0``.", + "description": "Minimum version of macOS required for this app to run, as `x.y.z`. For example, for macOS v10.4 and later, use `10.4.0`.", + "markdownDescription": "Minimum version of macOS required for this app to run, as `x.y.z`. For example, for macOS v10.4 and later, use `10.4.0`.", "pattern": "^\\d+\\.\\d+\\.\\d+$", "type": "string" }, "LSMultipleInstancesProhibited": { "title": "Lsmultipleinstancesprohibited", - "description": "Whether an app is prohibited from running simultaneously in multiple user sessions.\"", + "description": "Whether an app is prohibited from running simultaneously in multiple user sessions.", + "markdownDescription": "Whether an app is prohibited from running simultaneously in multiple user sessions.", "type": "boolean" }, "LSRequiresNativeExecution": { "title": "Lsrequiresnativeexecution", "description": "If true, prevent a universal binary from being run under Rosetta emulation on an Intel-based Mac.", + "markdownDescription": "If true, prevent a universal binary from being run under Rosetta emulation on an Intel-based Mac.", "type": "boolean" }, "NSSupportsAutomaticGraphicsSwitching": { "title": "Nssupportsautomaticgraphicsswitching", "description": "If true, allows an OpenGL app to utilize the integrated GPU.", + "markdownDescription": "If true, allows an OpenGL app to utilize the integrated GPU.", "type": "boolean" }, "UTExportedTypeDeclarations": { "title": "Utexportedtypedeclarations", "description": "The uniform type identifiers owned and exported by the app.", + "markdownDescription": "The uniform type identifiers owned and exported by the app.", "type": "array", "items": { "$ref": "#/definitions/UTTypeDeclarationModel" @@ -586,6 +661,7 @@ "UTImportedTypeDeclarations": { "title": "Utimportedtypedeclarations", "description": "The uniform type identifiers inherently supported, but not owned, by the app.", + "markdownDescription": "The uniform type identifiers inherently supported, but not owned, by the app.", "type": "array", "items": { "$ref": "#/definitions/UTTypeDeclarationModel" @@ -593,7 +669,8 @@ }, "entitlements": { "title": "Entitlements", - "description": "List of permissions to request for the launched application. See `the entitlements docs `__ for a full list of possible values.", + "description": "List of permissions to request for the launched application. See [the entitlements docs]( https://developer.apple.com/documentation/bundleresources/entitlements) for a full list of possible values.", + "markdownDescription": "List of permissions to request for the launched application. See [the entitlements docs]( https://developer.apple.com/documentation/bundleresources/entitlements) for a full list of possible values.", "type": "array", "items": { "type": "string", @@ -602,7 +679,8 @@ }, "link_in_bundle": { "title": "Link In Bundle", - "description": "Paths that should be symlinked into the shortcut app bundle. It takes a mapping of source to destination paths. Destination paths must be relative. Placeholder ``{{ MENU_ITEM_LOCATION }}`` can be useful.", + "description": "Paths that should be symlinked into the shortcut app bundle. It takes a mapping of source to destination paths. Destination paths must be relative. Placeholder `{{ MENU_ITEM_LOCATION }}` can be useful.", + "markdownDescription": "Paths that should be symlinked into the shortcut app bundle. It takes a mapping of source to destination paths. Destination paths must be relative. Placeholder `{{ MENU_ITEM_LOCATION }}` can be useful.", "type": "object", "additionalProperties": { "type": "string", @@ -612,11 +690,13 @@ "event_handler": { "title": "Event Handler", "description": "Required shell script logic to handle opened URL payloads. Note this feature requires macOS 10.14.4 or above.", + "markdownDescription": "Required shell script logic to handle opened URL payloads. Note this feature requires macOS 10.14.4 or above.", "minLength": 1, "type": "string" } }, - "additionalProperties": false + "additionalProperties": false, + "markdownDescription": "Mac-specific instructions. Check these URLs for more info:\n\n- `CF*` keys: see [Core Foundation Keys](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html)\n- `LS*` keys: see [Launch Services Keys](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html)\n- `entitlements`: see [Entitlements documentation](https://developer.apple.com/documentation/bundleresources/entitlements)" }, "Windows": { "title": "Windows", @@ -625,7 +705,8 @@ "properties": { "name": { "title": "Name", - "description": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See :class:`MenuItemNameDict` for details.", + "description": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See `MenuItemNameDict` for details.", + "markdownDescription": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See `MenuItemNameDict` for details.", "anyOf": [ { "type": "string", @@ -639,17 +720,20 @@ "description": { "title": "Description", "description": "A longer description of the menu item. Shown on popup messages.", + "markdownDescription": "A longer description of the menu item. Shown on popup messages.", "type": "string" }, "icon": { "title": "Icon", "description": "Path to the file representing or containing the icon.", + "markdownDescription": "Path to the file representing or containing the icon.", "minLength": 1, "type": "string" }, "command": { "title": "Command", "description": "Command to run with the menu item, expressed as a list of strings where each string is an argument.", + "markdownDescription": "Command to run with the menu item, expressed as a list of strings where each string is an argument.", "minItems": 1, "type": "array", "items": { @@ -659,35 +743,41 @@ "working_dir": { "title": "Working Dir", "description": "Working directory for the running process. Defaults to user directory on each platform.", + "markdownDescription": "Working directory for the running process. Defaults to user directory on each platform.", "minLength": 1, "type": "string" }, "precommand": { "title": "Precommand", "description": "(Simple, preferrably single-line) logic to run before the command is run. Runs before the environment is activated, if that applies.", + "markdownDescription": "(Simple, preferrably single-line) logic to run before the command is run. Runs before the environment is activated, if that applies.", "minLength": 1, "type": "string" }, "precreate": { "title": "Precreate", "description": "(Simple, preferrably single-line) logic to run before the shortcut is created.", + "markdownDescription": "(Simple, preferrably single-line) logic to run before the shortcut is created.", "minLength": 1, "type": "string" }, "activate": { "title": "Activate", - "description": "Whether to activate the target environment before running ``command``.", + "description": "Whether to activate the target environment before running `command`.", + "markdownDescription": "Whether to activate the target environment before running `command`.", "type": "boolean" }, "terminal": { "title": "Terminal", - "description": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if ``activate`` is true. On MacOS, the application will ignore command-line arguments.", + "description": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if `activate` is true. On MacOS, the application will ignore command-line arguments.", + "markdownDescription": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if `activate` is true. On MacOS, the application will ignore command-line arguments.", "type": "boolean" }, "desktop": { "title": "Desktop", "description": "Whether to create a desktop icon in addition to the Start Menu item.", "default": true, + "markdownDescription": "Whether to create a desktop icon in addition to the Start Menu item.", "type": "boolean" }, "quicklaunch": { @@ -695,17 +785,20 @@ "description": "DEPRECATED. Whether to create a quick launch icon in addition to the Start Menu item.", "default": false, "deprecated": true, + "markdownDescription": "DEPRECATED. Whether to create a quick launch icon in addition to the Start Menu item.", "type": "boolean" }, "terminal_profile": { "title": "Terminal Profile", "description": "Name of the Windows Terminal profile to create. This name must be unique across multiple installations because menuinst will overwrite Terminal profiles with the same name.", + "markdownDescription": "Name of the Windows Terminal profile to create. This name must be unique across multiple installations because menuinst will overwrite Terminal profiles with the same name.", "minLength": 1, "type": "string" }, "url_protocols": { "title": "Url Protocols", "description": "URL protocols that will be associated with this program.", + "markdownDescription": "URL protocols that will be associated with this program.", "type": "array", "items": { "type": "string", @@ -715,6 +808,7 @@ "file_extensions": { "title": "File Extensions", "description": "File extensions that will be associated with this program.", + "markdownDescription": "File extensions that will be associated with this program.", "type": "array", "items": { "type": "string", @@ -723,22 +817,25 @@ }, "app_user_model_id": { "title": "App User Model Id", - "description": "Identifier used in Windows 7 and above to associate processes, files and windows with a particular application. If your shortcut produces duplicated icons, you need to define this field. If not set, it will default to ``Menuinst.``.\n\nSee `AppUserModelID docs `__ for more information on the required string format.", + "description": "Identifier used in Windows 7 and above to associate processes, files and windows with a particular application. If your shortcut produces duplicated icons, you need to define this field. If not set, it will default to `Menuinst.`.\n\nSee [AppUserModelID docs]( https://learn.microsoft.com/en-us/windows/win32/shell/appids#how-to-form-an-application-defined-appusermodelid) for more information on the required string format.", + "markdownDescription": "Identifier used in Windows 7 and above to associate processes, files and windows with a particular application. If your shortcut produces duplicated icons, you need to define this field. If not set, it will default to `Menuinst.`.\n\nSee [AppUserModelID docs]( https://learn.microsoft.com/en-us/windows/win32/shell/appids#how-to-form-an-application-defined-appusermodelid) for more information on the required string format.", "maxLength": 128, "pattern": "\\S+\\.\\S+", "type": "string" } }, - "additionalProperties": false + "additionalProperties": false, + "markdownDescription": "Windows-specific instructions. You can override global keys here if needed" }, "Platforms": { "title": "Platforms", - "description": "Platform specific options.\n\nNote each of these fields supports the same keys as the top-level :class:`MenuItem`\n(sans ``platforms`` itself), in case overrides are needed.", + "description": "Platform specific options.\n\nNote each of these fields supports the same keys as the top-level `MenuItem`\n(sans `platforms` itself), in case overrides are needed.", "type": "object", "properties": { "linux": { "title": "Linux", - "description": "Options for Linux. See :class:`Linux` model for details.", + "description": "Options for Linux. See `Linux` model for details.", + "markdownDescription": "Options for Linux. See `Linux` model for details.", "allOf": [ { "$ref": "#/definitions/Linux" @@ -747,7 +844,8 @@ }, "osx": { "title": "Osx", - "description": "Options for macOS. See :class:`MacOS` model for details.", + "description": "Options for macOS. See `MacOS` model for details.", + "markdownDescription": "Options for macOS. See `MacOS` model for details.", "allOf": [ { "$ref": "#/definitions/MacOS" @@ -756,7 +854,8 @@ }, "win": { "title": "Win", - "description": "Options for Windows. See :class:`Windows` model for details.", + "description": "Options for Windows. See `Windows` model for details.", + "markdownDescription": "Options for Windows. See `Windows` model for details.", "allOf": [ { "$ref": "#/definitions/Windows" @@ -764,7 +863,8 @@ ] } }, - "additionalProperties": false + "additionalProperties": false, + "markdownDescription": "Platform specific options.\n\nNote each of these fields supports the same keys as the top-level `MenuItem`\n(sans `platforms` itself), in case overrides are needed." }, "MenuItem": { "title": "MenuItem", @@ -773,7 +873,8 @@ "properties": { "name": { "title": "Name", - "description": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See :class:`MenuItemNameDict` for details.", + "description": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See `MenuItemNameDict` for details.", + "markdownDescription": "The name of the menu item. Can be a dictionary if the name depends on installation parameters. See `MenuItemNameDict` for details.", "anyOf": [ { "type": "string", @@ -787,11 +888,13 @@ "description": { "title": "Description", "description": "A longer description of the menu item. Shown on popup messages.", + "markdownDescription": "A longer description of the menu item. Shown on popup messages.", "type": "string" }, "command": { "title": "Command", "description": "Command to run with the menu item, expressed as a list of strings where each string is an argument.", + "markdownDescription": "Command to run with the menu item, expressed as a list of strings where each string is an argument.", "minItems": 1, "type": "array", "items": { @@ -801,42 +904,49 @@ "icon": { "title": "Icon", "description": "Path to the file representing or containing the icon.", + "markdownDescription": "Path to the file representing or containing the icon.", "minLength": 1, "type": "string" }, "precommand": { "title": "Precommand", "description": "(Simple, preferrably single-line) logic to run before the command is run. Runs before the environment is activated, if that applies.", + "markdownDescription": "(Simple, preferrably single-line) logic to run before the command is run. Runs before the environment is activated, if that applies.", "minLength": 1, "type": "string" }, "precreate": { "title": "Precreate", "description": "(Simple, preferrably single-line) logic to run before the shortcut is created.", + "markdownDescription": "(Simple, preferrably single-line) logic to run before the shortcut is created.", "minLength": 1, "type": "string" }, "working_dir": { "title": "Working Dir", "description": "Working directory for the running process. Defaults to user directory on each platform.", + "markdownDescription": "Working directory for the running process. Defaults to user directory on each platform.", "minLength": 1, "type": "string" }, "activate": { "title": "Activate", - "description": "Whether to activate the target environment before running ``command``.", + "description": "Whether to activate the target environment before running `command`.", "default": true, + "markdownDescription": "Whether to activate the target environment before running `command`.", "type": "boolean" }, "terminal": { "title": "Terminal", - "description": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if ``activate`` is true. On MacOS, the application will ignore command-line arguments.", + "description": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if `activate` is true. On MacOS, the application will ignore command-line arguments.", "default": false, + "markdownDescription": "Whether run the program in a terminal/console or not. On Windows, it only has an effect if `activate` is true. On MacOS, the application will ignore command-line arguments.", "type": "boolean" }, "platforms": { "title": "Platforms", "description": "Platform-specific options. Presence of a platform field enables menu items in that platform.", + "markdownDescription": "Platform-specific options. Presence of a platform field enables menu items in that platform.", "allOf": [ { "$ref": "#/definitions/Platforms" @@ -850,7 +960,8 @@ "command", "platforms" ], - "additionalProperties": false + "additionalProperties": false, + "markdownDescription": "Instructions to create a menu item across operating systems." } } } From 806e1c22659fe05c41c7b89a2b74c94c74423ac6 Mon Sep 17 00:00:00 2001 From: jaimergp Date: Wed, 27 Nov 2024 20:28:33 +0100 Subject: [PATCH 8/9] pre-commit --- docs/source/conf.py | 4 +++- menuinst/_schema.py | 13 +++++++++---- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index d930ba3f..4148b3a4 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -125,13 +125,15 @@ # Custom hooks os.environ["SPHINX_RUNNING"] = "1" + def docstring(app, what, name, obj, options, lines): """Transform MD to RST for autodoc""" - md = '\n'.join(lines) + md = '\n'.join(lines) ast = commonmark.Parser().parse(md) rst = commonmark.ReStructuredTextRenderer().render(ast) lines.clear() lines += rst.splitlines() + def setup(app): app.connect('autodoc-process-docstring', docstring) diff --git a/menuinst/_schema.py b/menuinst/_schema.py index ce80e69d..2c5d6f10 100644 --- a/menuinst/_schema.py +++ b/menuinst/_schema.py @@ -16,11 +16,13 @@ try: from pydantic.v1 import BaseModel as _BaseModel - from pydantic.v1 import Field as _Field, conlist, constr + from pydantic.v1 import Field as _Field + from pydantic.v1 import conlist, constr except ImportError: # pydantic v1 from pydantic import BaseModel as _BaseModel - from pydantic import Field as _Field, conlist, constr + from pydantic import Field as _Field + from pydantic import conlist, constr log = getLogger(__name__) @@ -505,7 +507,9 @@ class UTTypeDeclarationModel(BaseModel): ) LSApplicationCategoryType: Optional[constr(regex=r"^public\.app-category\.\S+$")] = Field( None, - description=("The App Store uses this string to determine the appropriate categorization."), + description=( + "The App Store uses this string to determine the appropriate categorization." + ), ) LSBackgroundOnly: Optional[bool] = Field( None, @@ -546,7 +550,8 @@ class UTTypeDeclarationModel(BaseModel): description=("If true, allows an OpenGL app to utilize the integrated GPU."), ) UTExportedTypeDeclarations: Optional[List[UTTypeDeclarationModel]] = Field( - None, description=("The uniform type identifiers owned and exported by the app."), + None, + description=("The uniform type identifiers owned and exported by the app."), ) UTImportedTypeDeclarations: Optional[List[UTTypeDeclarationModel]] = Field( None, From d082c827b081c2b793d051518307795f3231522a Mon Sep 17 00:00:00 2001 From: jaimergp Date: Wed, 27 Nov 2024 20:47:06 +0100 Subject: [PATCH 9/9] also clean model descriptions --- menuinst/_schema.py | 4 +++- menuinst/data/menuinst.schema.json | 16 ++++++++-------- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/menuinst/_schema.py b/menuinst/_schema.py index 2c5d6f10..98793a61 100644 --- a/menuinst/_schema.py +++ b/menuinst/_schema.py @@ -47,7 +47,9 @@ class Config: @staticmethod def schema_extra(schema, model): if description := schema.get("description"): - schema.setdefault("markdownDescription", description) + description = _clean_description(description) + schema["description"] = description + schema["markdownDescription"] = description def Field(*args, **kwargs): diff --git a/menuinst/data/menuinst.schema.json b/menuinst/data/menuinst.schema.json index 09ac7931..8491ce9f 100644 --- a/menuinst/data/menuinst.schema.json +++ b/menuinst/data/menuinst.schema.json @@ -50,7 +50,7 @@ "definitions": { "MenuItemNameDict": { "title": "MenuItemNameDict", - "description": "Variable menu item name.\nUse this dictionary if the menu item name depends on installation parameters\nsuch as the target environment.", + "description": "Variable menu item name. Use this dictionary if the menu item name depends on installation parameters such as the target environment.", "type": "object", "properties": { "target_environment_is_base": { @@ -69,11 +69,11 @@ } }, "additionalProperties": false, - "markdownDescription": "Variable menu item name.\nUse this dictionary if the menu item name depends on installation parameters\nsuch as the target environment." + "markdownDescription": "Variable menu item name. Use this dictionary if the menu item name depends on installation parameters such as the target environment." }, "Linux": { "title": "Linux", - "description": "Linux-specific instructions.\n\nCheck the [Desktop entry specification](\nhttps://specifications.freedesktop.org/desktop-entry-spec/latest/recognized-keys.html)\nfor more details.", + "description": "Linux-specific instructions.\n\nCheck the [Desktop entry specification]( https://specifications.freedesktop.org/desktop-entry-spec/latest/recognized-keys.html) for more details.", "type": "object", "properties": { "name": { @@ -314,7 +314,7 @@ } }, "additionalProperties": false, - "markdownDescription": "Linux-specific instructions.\n\nCheck the [Desktop entry specification](\nhttps://specifications.freedesktop.org/desktop-entry-spec/latest/recognized-keys.html)\nfor more details." + "markdownDescription": "Linux-specific instructions.\n\nCheck the [Desktop entry specification]( https://specifications.freedesktop.org/desktop-entry-spec/latest/recognized-keys.html) for more details." }, "CFBundleURLTypesModel": { "title": "CFBundleURLTypesModel", @@ -478,7 +478,7 @@ }, "MacOS": { "title": "MacOS", - "description": "Mac-specific instructions. Check these URLs for more info:\n\n- `CF*` keys: see [Core Foundation Keys](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html)\n- `LS*` keys: see [Launch Services Keys](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html)\n- `entitlements`: see [Entitlements documentation](https://developer.apple.com/documentation/bundleresources/entitlements)", + "description": "Mac-specific instructions. Check these URLs for more info:\n\n- `CF*` keys: see [Core Foundation Keys](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html) - `LS*` keys: see [Launch Services Keys](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html) - `entitlements`: see [Entitlements documentation](https://developer.apple.com/documentation/bundleresources/entitlements)", "type": "object", "properties": { "name": { @@ -696,7 +696,7 @@ } }, "additionalProperties": false, - "markdownDescription": "Mac-specific instructions. Check these URLs for more info:\n\n- `CF*` keys: see [Core Foundation Keys](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html)\n- `LS*` keys: see [Launch Services Keys](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html)\n- `entitlements`: see [Entitlements documentation](https://developer.apple.com/documentation/bundleresources/entitlements)" + "markdownDescription": "Mac-specific instructions. Check these URLs for more info:\n\n- `CF*` keys: see [Core Foundation Keys](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html) - `LS*` keys: see [Launch Services Keys](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html) - `entitlements`: see [Entitlements documentation](https://developer.apple.com/documentation/bundleresources/entitlements)" }, "Windows": { "title": "Windows", @@ -829,7 +829,7 @@ }, "Platforms": { "title": "Platforms", - "description": "Platform specific options.\n\nNote each of these fields supports the same keys as the top-level `MenuItem`\n(sans `platforms` itself), in case overrides are needed.", + "description": "Platform specific options.\n\nNote each of these fields supports the same keys as the top-level `MenuItem` (sans `platforms` itself), in case overrides are needed.", "type": "object", "properties": { "linux": { @@ -864,7 +864,7 @@ } }, "additionalProperties": false, - "markdownDescription": "Platform specific options.\n\nNote each of these fields supports the same keys as the top-level `MenuItem`\n(sans `platforms` itself), in case overrides are needed." + "markdownDescription": "Platform specific options.\n\nNote each of these fields supports the same keys as the top-level `MenuItem` (sans `platforms` itself), in case overrides are needed." }, "MenuItem": { "title": "MenuItem",