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. diff --git a/docs/reference/platforms/web/static.rst b/docs/reference/platforms/web/static.rst index 7bc9cdc7e..0a06ca6d5 100644 --- a/docs/reference/platforms/web/static.rst +++ b/docs/reference/platforms/web/static.rst @@ -97,3 +97,124 @@ and change the default PyScript app name, you could use:: [[runtimes]] src = "https://example.com/custom/pyodide.js" """ + +Deployment Configuration +======================== + +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. + +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. + +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``: + +.. code-block:: toml + + implementation = "pyscript" + + [pyscript] + version = "2024.11.1" + +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. + +``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 +will build the final ``pyproject.toml`` file using the following procedure: + +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. + +Inserts +------- + +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. + +When building an app for deployment, Briefcase will: + +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 Slots +~~~~~~~~~~~~ + +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: + + .. code-block:: html + + + + +* CSS/JavaScript: + + .. 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 of ``index.html`` +* ``head-python``: Content for the ```` used to configure the Python interpreter +* ``body-start``: Content at the start of the ```` +* ``body-python``: Content in the ```` used to configure the Python interpreter +* ``body-end``: Content at the end of the ```` +* ``css``: CSS content to be included in the site stylesheet. + +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/~ + +Where: + +* 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. + +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`` 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`` 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