From 7c7acc99bc66f258966a03873bab73da406b9dc1 Mon Sep 17 00:00:00 2001 From: kavi2du Date: Wed, 15 Oct 2025 11:49:13 +0800 Subject: [PATCH 1/7] Update static.rst documentation Update static.rst to reflect the new web platform insert system and deployment config --- docs/reference/platforms/web/static.rst | 42 +++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/reference/platforms/web/static.rst b/docs/reference/platforms/web/static.rst index 7bc9cdc7e..df81cd2cf 100644 --- a/docs/reference/platforms/web/static.rst +++ b/docs/reference/platforms/web/static.rst @@ -97,3 +97,45 @@ and change the default PyScript app name, you could use:: [[runtimes]] src = "https://example.com/custom/pyodide.js" """ + +Deployment Configuration +======================== + +Web packages can include deployment configuration to control how Briefcase builds +and deploys web applications. The deployment process relies on a ``config.toml`` +file and associated deployment files included in Python packages. + +config.toml +----------- + +A package can specify deployment settings through a ``config.toml`` file located +at ``/deploy/config.toml``. The deployment configuration file accepts the +following information: + +* ``implementation``: The web implementation to use (currently only ``"pyscript"`` + is supported). If not specified, defaults to ``"pyscript"``. +* ``pyscript.version``: The PyScript version to use (e.g., ``"2024.11.1"``). If not + specified, Briefcase will use its default PyScript version. + +Example ``config.toml``:: + + implementation = "pyscript" + + [pyscript] + version = "2024.11.1" + +pyscript.toml +------------- + +A package can include a base ``pyscript.toml`` file located at +``/deploy/pyscript.toml``. The base configuration in this file serves as +the foundation for Briefcase to generate the final ``pyscript.toml`` file. +Briefcase performs the following operations when processing this file: + +1. The system reads the base ``pyscript.toml`` file from the package directory. +2. The system adds the ``packages`` list which contains all wheel files to the configuration. +3. Merge in any :attr:`extra_pyscript_toml_content` from ``pyproject.toml`` + +A Briefcase project must have only one package that defines deployment configuration +through a ``config.toml`` file. The system will produce an error when multiple packages +in the dependencies attempt to define deployment settings. From a322c23919f66c0034f1d350bfb86f1e7fa13ebf Mon Sep 17 00:00:00 2001 From: kavi2du Date: Wed, 15 Oct 2025 12:15:01 +0800 Subject: [PATCH 2/7] Add insert system section --- docs/reference/platforms/web/static.rst | 45 +++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/reference/platforms/web/static.rst b/docs/reference/platforms/web/static.rst index df81cd2cf..1871884c2 100644 --- a/docs/reference/platforms/web/static.rst +++ b/docs/reference/platforms/web/static.rst @@ -139,3 +139,48 @@ Briefcase performs the following operations when processing this file: A Briefcase project must have only one package that defines deployment configuration through a ``config.toml`` file. The system will produce an error when multiple packages in the dependencies attempt to define deployment settings. + +Insert System +============= + +The insert system allows Python packages to inject HTML, CSS, and JavaScript content +into specific locations (called "slots") in the generated web application. This is the +recommended way to add custom web resources to your Briefcase web application. + +How Inserts Work +---------------- + +The build process of Briefcase performs the following operations: + +1. The system scans through all wheel files to detect insert content. +2. The system organizes collected inserts according to their target files and slot names. +3. The system writes the accumulated content into designated slots in the target files. + +Insert Markers +-------------- + +the target files such as ``index.html`` or ``briefcase.css`` need to include marker +comments that indicate where inserts should be placed. Two marker formats are supported: + +**HTML markers:** + +.. code-block:: html + + + + +**CSS/JavaScript markers:** + +.. code-block:: css + + /*@@ slot-name:start @@*/ + /*@@ slot-name:end @@*/ + +Common insert slots in Briefcase web templates include: + +* ``head``: Content to insert in the HTML ```` section +* ``head-python``: Python-related content for the ```` (used by PyScript) +* ``body-start``: Content at the start of the ```` +* ``body-python``: Python execution content in the ```` (used by PyScript) +* ``body-end``: Content at the end of the ```` +* ``css``: Custom CSS content in ``static/css/briefcase.css`` From 33e2665a90069e4ec20ee5aa4472e9695303aa31 Mon Sep 17 00:00:00 2001 From: kavi2du Date: Wed, 15 Oct 2025 12:43:38 +0800 Subject: [PATCH 3/7] Add creating insert files section --- docs/reference/platforms/web/static.rst | 27 +++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/reference/platforms/web/static.rst b/docs/reference/platforms/web/static.rst index 1871884c2..428ea25eb 100644 --- a/docs/reference/platforms/web/static.rst +++ b/docs/reference/platforms/web/static.rst @@ -184,3 +184,30 @@ Common insert slots in Briefcase web templates include: * ``body-python``: Python execution content in the ```` (used by PyScript) * ``body-end``: Content at the end of the ```` * ``css``: Custom CSS content in ``static/css/briefcase.css`` + +Creating Insert Files +--------------------- + +Python packages can include inserts by placing files inside the ``deploy/inserts/`` +directory which must use this naming convention: + +.. code-block:: text + + /deploy/inserts/~ + +Where: + +* The target file path in relation to the project root directory appears as +```` (e.g., ``index.html`` or ``static/css/briefcase.css``). +* The slot name for insertion appears as ```` +(e.g., ``head``, ``body-end``, ``css``). +* The tilde (``~``) character separates the target path from the slot name. + +**Examples:** + +* ``mypackage/deploy/inserts/index.html~head`` - Inserts into the ``head`` slot of + ``index.html`` +* ``mypackage/deploy/inserts/index.html~body-end`` - Inserts into the ``body-end`` + slot of ``index.html`` +* ``mypackage/deploy/inserts/static/css/briefcase.css~css`` - Inserts into the ``css`` + slot of ``static/css/briefcase.css`` From 1ffac28fd19a3542cbcc93cbc7e766adf9490de2 Mon Sep 17 00:00:00 2001 From: kavi2du Date: Wed, 15 Oct 2025 13:11:49 +0800 Subject: [PATCH 4/7] Add insert content format and legacy static file handling sections --- docs/reference/platforms/web/static.rst | 58 +++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 4 deletions(-) diff --git a/docs/reference/platforms/web/static.rst b/docs/reference/platforms/web/static.rst index 428ea25eb..d7e8fa237 100644 --- a/docs/reference/platforms/web/static.rst +++ b/docs/reference/platforms/web/static.rst @@ -197,10 +197,8 @@ directory which must use this naming convention: Where: -* The target file path in relation to the project root directory appears as -```` (e.g., ``index.html`` or ``static/css/briefcase.css``). -* The slot name for insertion appears as ```` -(e.g., ``head``, ``body-end``, ``css``). +* The target file path in relation to the project root directory appears as ```` (e.g., ``index.html`` or ``static/css/briefcase.css``). +* The slot name for insertion appears as ```` (e.g., ``head``, ``body-end``, ``css``). * The tilde (``~``) character separates the target path from the slot name. **Examples:** @@ -211,3 +209,55 @@ Where: slot of ``index.html`` * ``mypackage/deploy/inserts/static/css/briefcase.css~css`` - Inserts into the ``css`` slot of ``static/css/briefcase.css`` + +Insert Content Format +--------------------- + +The content of insert files needs to follow the format given below which the target system requires for processing: + +* For HTML slots, provide HTML content +* For CSS slots, provide CSS content +* For JavaScript slots, provide JavaScript content + +The system adds automatic banner comments to each insert which show their source package information. The system processes inserts from the same package and slot in order of their sorted sequence. + +**Example HTML insert** (``mypackage/deploy/inserts/index.html~head``):: + + + + +**Example CSS insert** (``mypackage/deploy/inserts/static/css/briefcase.css~css``):: + + .my-custom-class { + color: blue; + font-weight: bold; + } + +Legacy Static Files (Deprecated) +================================= + +.. deprecated:: 0.3.21 + The legacy static file system has been deprecated in favor of the insert system. + +Before the insertion system was introduced, packages could place their static CSS files inside a ``/static`` directory within their package structure. The system would automatically find these files to include them in ``static/css/briefcase.css``. + +Currently, the previous method has been marked for removal. When Briefcase detects CSS files located under the ``/static/`` directory of a wheel it performs the following actions: + +1. The system displays a deprecation warning to users. +2. The system convert the CSS content into an insert which will be added to ``static/css/briefcase.css``. +3. The system adds a comment which shows the file came from a legacy static file. + +**Migration to inserts:** + +Instead of:: + + mypackage/ + static/ + mystyles.css + +Use:: + + mypackage/ + deploy/ + inserts/ + static/css/briefcase.css~css From 6276701004e6494bffc28a23a5860cfda9f7aa3d Mon Sep 17 00:00:00 2001 From: kavi2du Date: Wed, 15 Oct 2025 13:17:44 +0800 Subject: [PATCH 5/7] Add change note --- changes/2511.misc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changes/2511.misc.rst diff --git a/changes/2511.misc.rst b/changes/2511.misc.rst new file mode 100644 index 000000000..fa35271d4 --- /dev/null +++ b/changes/2511.misc.rst @@ -0,0 +1 @@ +The Briefcase documentation now includes the missing documentation for the recently introduced asset-gathering strategy for web projects. From 64c0304757f59afc1dd9b7da8483daebde2d3fbe Mon Sep 17 00:00:00 2001 From: Kavidu <132393780+kavi2du@users.noreply.github.com> Date: Wed, 15 Oct 2025 14:54:52 +0800 Subject: [PATCH 6/7] Update static.rst --- docs/reference/platforms/web/static.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/platforms/web/static.rst b/docs/reference/platforms/web/static.rst index d7e8fa237..272d39953 100644 --- a/docs/reference/platforms/web/static.rst +++ b/docs/reference/platforms/web/static.rst @@ -137,7 +137,7 @@ Briefcase performs the following operations when processing this file: 3. Merge in any :attr:`extra_pyscript_toml_content` from ``pyproject.toml`` A Briefcase project must have only one package that defines deployment configuration -through a ``config.toml`` file. The system will produce an error when multiple packages +through a ``config.toml`` file located at ``/deploy/config.toml``. The system will produce an error when multiple packages in the dependencies attempt to define deployment settings. Insert System From 80dcef759deb9d607784a4131a920f9cef7ccd48 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Tue, 21 Oct 2025 15:28:00 +0800 Subject: [PATCH 7/7] Edits for static web deployment docs. --- docs/reference/platforms/web/static.rst | 177 +++++++++--------------- docs/spelling_wordlist | 1 + 2 files changed, 68 insertions(+), 110 deletions(-) diff --git a/docs/reference/platforms/web/static.rst b/docs/reference/platforms/web/static.rst index 272d39953..0a06ca6d5 100644 --- a/docs/reference/platforms/web/static.rst +++ b/docs/reference/platforms/web/static.rst @@ -101,163 +101,120 @@ and change the default PyScript app name, you could use:: Deployment Configuration ======================== -Web packages can include deployment configuration to control how Briefcase builds -and deploys web applications. The deployment process relies on a ``config.toml`` -file and associated deployment files included in Python packages. +Wheels can include information related to deployment that Briefcase will use to +control how to serve web applications. This includes configuration of the Python +runtime environment (such as the PyScript version), as well as snippets of HTML, +CSS or JavaScript that are required for a wheel to behave as expected at runtime. -config.toml ------------ +The deployment configuration is provided by including a ``deploy`` folder in the +contents of the wheel as a child of the top level package folder. For example, if you +have a package named ``mypackage``, any content in the wheel in the ``mypackage/deploy`` +folder will be used by Briefcase to aid deployment as a web site. -A package can specify deployment settings through a ``config.toml`` file located -at ``/deploy/config.toml``. The deployment configuration file accepts the -following information: +The following files and file types can be included in the deploy directory: + +``config.toml`` +--------------- + +Deployment settings are defined using a ``config.toml`` file located in the ``deploy`` +folder. The deployment configuration file accepts the following information: * ``implementation``: The web implementation to use (currently only ``"pyscript"`` is supported). If not specified, defaults to ``"pyscript"``. + * ``pyscript.version``: The PyScript version to use (e.g., ``"2024.11.1"``). If not specified, Briefcase will use its default PyScript version. -Example ``config.toml``:: +Example ``config.toml``: + +.. code-block:: toml implementation = "pyscript" [pyscript] version = "2024.11.1" -pyscript.toml -------------- - -A package can include a base ``pyscript.toml`` file located at -``/deploy/pyscript.toml``. The base configuration in this file serves as -the foundation for Briefcase to generate the final ``pyscript.toml`` file. -Briefcase performs the following operations when processing this file: +A Briefcase project must have only one package that defines deployment configuration +through a ``config.toml`` file. Briefcase will raise an error if multiple packages in +the dependencies attempt to define deployment settings. -1. The system reads the base ``pyscript.toml`` file from the package directory. -2. The system adds the ``packages`` list which contains all wheel files to the configuration. -3. Merge in any :attr:`extra_pyscript_toml_content` from ``pyproject.toml`` +``pyscript.toml`` +----------------- -A Briefcase project must have only one package that defines deployment configuration -through a ``config.toml`` file located at ``/deploy/config.toml``. The system will produce an error when multiple packages -in the dependencies attempt to define deployment settings. +A package can include a base ``pyscript.toml`` file located at +``/deploy/pyscript.toml``. The base configuration in this file serves as the +foundation for Briefcase to generate the final ``pyscript.toml`` file. Briefcase +will build the final ``pyproject.toml`` file using the following procedure: -Insert System -============= +1. Briefcase reads the base ``pyscript.toml`` file from the wheel's ``deploy`` + directory. +2. Briefcase will add a ``packages`` definition to that base ``pyscript.toml`` that + matches the requirements defined in your project's ``pyproject.toml``. +3. Any :attr:`extra_pyscript_toml_content` from ``pyproject.toml`` will be merged over + the top of any existing configuration. -The insert system allows Python packages to inject HTML, CSS, and JavaScript content -into specific locations (called "slots") in the generated web application. This is the -recommended way to add custom web resources to your Briefcase web application. +Inserts +------- -How Inserts Work ----------------- +A package can provide snippets of HTML, CSS, and JavaScript content that are to be +inserted into specific locations (called "slots") in the generated web application. This +is the recommended way to add custom web resources to your Briefcase web application. -The build process of Briefcase performs the following operations: +When building an app for deployment, Briefcase will: -1. The system scans through all wheel files to detect insert content. -2. The system organizes collected inserts according to their target files and slot names. -3. The system writes the accumulated content into designated slots in the target files. +1. Scans through all wheel files to detect insert content. +2. Organize collected inserts according to their target files and slot names. +3. Writes the accumulated content into designated slots in the target files. -Insert Markers --------------- +Insert Slots +~~~~~~~~~~~~ -the target files such as ``index.html`` or ``briefcase.css`` need to include marker -comments that indicate where inserts should be placed. Two marker formats are supported: +Any file generated by the Briefcase app template can to include slots that indicate +where inserts should be placed. These slots are code comments that have a specific +format that Briefcase can use to identify the location for inserted content: -**HTML markers:** +* HTML: -.. code-block:: html + .. code-block:: html - - + + -**CSS/JavaScript markers:** +* CSS/JavaScript: -.. code-block:: css + .. code-block:: css - /*@@ slot-name:start @@*/ - /*@@ slot-name:end @@*/ + /*@@ slot-name:start @@*/ + /*@@ slot-name:end @@*/ Common insert slots in Briefcase web templates include: -* ``head``: Content to insert in the HTML ```` section -* ``head-python``: Python-related content for the ```` (used by PyScript) +* ``head``: Content to insert in the HTML ```` section of ``index.html`` +* ``head-python``: Content for the ```` used to configure the Python interpreter * ``body-start``: Content at the start of the ```` -* ``body-python``: Python execution content in the ```` (used by PyScript) +* ``body-python``: Content in the ```` used to configure the Python interpreter * ``body-end``: Content at the end of the ```` -* ``css``: Custom CSS content in ``static/css/briefcase.css`` +* ``css``: CSS content to be included in the site stylesheet. -Creating Insert Files ---------------------- +Defining Insert Files +~~~~~~~~~~~~~~~~~~~~~ Python packages can include inserts by placing files inside the ``deploy/inserts/`` directory which must use this naming convention: .. code-block:: text - /deploy/inserts/~ + /deploy/inserts/~ Where: -* The target file path in relation to the project root directory appears as ```` (e.g., ``index.html`` or ``static/css/briefcase.css``). -* The slot name for insertion appears as ```` (e.g., ``head``, ``body-end``, ``css``). +* The target file path is specified in relation to the project root directory appears as + ```` (e.g., ``index.html`` or ``static/css/briefcase.css``). * The tilde (``~``) character separates the target path from the slot name. -**Examples:** +For example, a package named ``mypackage`` could include the following files as inserts: * ``mypackage/deploy/inserts/index.html~head`` - Inserts into the ``head`` slot of - ``index.html`` -* ``mypackage/deploy/inserts/index.html~body-end`` - Inserts into the ``body-end`` - slot of ``index.html`` + ``index.html`` in the root of the deployment directory * ``mypackage/deploy/inserts/static/css/briefcase.css~css`` - Inserts into the ``css`` slot of ``static/css/briefcase.css`` - -Insert Content Format ---------------------- - -The content of insert files needs to follow the format given below which the target system requires for processing: - -* For HTML slots, provide HTML content -* For CSS slots, provide CSS content -* For JavaScript slots, provide JavaScript content - -The system adds automatic banner comments to each insert which show their source package information. The system processes inserts from the same package and slot in order of their sorted sequence. - -**Example HTML insert** (``mypackage/deploy/inserts/index.html~head``):: - - - - -**Example CSS insert** (``mypackage/deploy/inserts/static/css/briefcase.css~css``):: - - .my-custom-class { - color: blue; - font-weight: bold; - } - -Legacy Static Files (Deprecated) -================================= - -.. deprecated:: 0.3.21 - The legacy static file system has been deprecated in favor of the insert system. - -Before the insertion system was introduced, packages could place their static CSS files inside a ``/static`` directory within their package structure. The system would automatically find these files to include them in ``static/css/briefcase.css``. - -Currently, the previous method has been marked for removal. When Briefcase detects CSS files located under the ``/static/`` directory of a wheel it performs the following actions: - -1. The system displays a deprecation warning to users. -2. The system convert the CSS content into an insert which will be added to ``static/css/briefcase.css``. -3. The system adds a comment which shows the file came from a legacy static file. - -**Migration to inserts:** - -Instead of:: - - mypackage/ - static/ - mystyles.css - -Use:: - - mypackage/ - deploy/ - inserts/ - static/css/briefcase.css~css diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist index 52bf71067..1b03f28ca 100644 --- a/docs/spelling_wordlist +++ b/docs/spelling_wordlist @@ -86,6 +86,7 @@ sandboxed sandboxing scrollable Setuptools +stylesheet subdirectories subdirectory subfolders