Convert settings into attribute references.

changes/2341.doc.rst

@@ -0,0 +1 @@
+References to Briefcase's settings are now hyperlinked for ease of cross-referencing.

docs/background/faq.rst

@@ -38,10 +38,10 @@ with Briefcase by testing for the existence of the ``Briefcase-Version`` tag::
 Can I use third-party Python packages in my app?
 ------------------------------------------------
 
-Yes! Briefcase uses ``pip`` to install third-party packages into your app bundle.
-As long as the package is available on PyPI, or you can provide a wheel file for
-the package, it can be added to the ``requires`` declaration in your
-``pyproject.toml`` file and used by your app at runtime.
+Yes! Briefcase uses ``pip`` to install third-party packages into your app bundle. As
+long as the package is available on PyPI, or you can provide a wheel file for the
+package, it can be added to the :attr:`requires` declaration in your ``pyproject.toml``
+file and used by your app at runtime.
 
 If the package is pure-Python (i.e., it does not contain a binary library), that's
 all you need to do.

docs/conf.py

@@ -82,7 +82,7 @@
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-# add_module_names = True
+add_module_names = False
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.

docs/how-to/access-packaging-metadata.rst

@@ -41,18 +41,18 @@ contains the following identifying keys:
 It will also have the following keys, derived from your application's
 ``pyproject.toml`` configuration:
 
-  * **Name** - ``app_name``
-  * **Formal-Name** - ``formal_name``
-  * **App-ID** - ``bundle`` and ``app_name``, joined with a ``.``
-  * **Version** - ``version``
-  * **Summary** - ``description``
+  * **Name** - :attr:`app_name`
+  * **Formal-Name** - :attr:`formal_name`
+  * **App-ID** - :attr:`bundle` and :attr:`app_name`, joined with a ``.``
+  * **Version** - :attr:`version`
+  * **Summary** - :attr:`description`
 
 The metadata may also contain the following keys, if they have been defined
 in your app's ``pyproject.toml`` configuration:
 
-  * **Home-page** - ``url``
-  * **Author** - ``author``
-  * **Author-email** - ``author_email``
+  * **Home-page** - :attr:`url`
+  * **Author** - :attr:`author`
+  * **Author-email** - :attr:`author_email`
 
 For example, the metadata for the app constructed by the `BeeWare Tutorial
 <https://docs.beeware.org/en/latest/tutorial/tutorial-1.html>`_ would

docs/how-to/cli-apps.rst

@@ -13,7 +13,7 @@ basics of Briefcase and have completed the `BeeWare Tutorial
 We'll cover:
 
 1. How selecting "Console" changes your project configuration
-2. The ``console_app`` flag in ``pyproject.toml``
+2. The :attr:`console_app` flag in ``pyproject.toml``
 3. How Briefcase handles command-line arguments
 4. Operational differences in how console apps run and display output
 5. Packaging differences specific to console apps (e.g., ``.pkg`` bundles on macOS)

docs/how-to/external-apps.rst

@@ -20,15 +20,15 @@ Configuring an external app
 ---------------------------
 
 The process of configuring an external app is mostly the same as a normal Briefcase app,
-with one important difference: you do *not* define a ``sources`` entry, but instead
-define a ``external_package_path``. The ``external_package_path`` should be the content
+with one important difference: you do *not* define a :attr:`sources` entry, but instead
+define an :attr:`external_package_path`. This should be the content
 produced by your build tool that you want to distribute to end users.
 
 macOS
 ~~~~~
 
-On macOS, the ``external_package_path`` should be the location of the ``.app`` bundle
-that you want to distribute to users. The configured ``formal_name`` must match the name
+On macOS, the :attr:`external_package_path` should be the location of the ``.app`` bundle
+that you want to distribute to users. The configured :attr:`formal_name` must match the name
 of the app bundle (e.g., ``Hello World.app`` should use a formal name of ``Hello
 World``); the ``app_name`` will be used for the shortcut installed in ``/usr/local/bin``
 when creating a :doc:`console app </how-to/cli-apps>`.
@@ -42,28 +42,28 @@ standalone binaries.
 Linux
 ~~~~~
 
-On Linux, the ``external_package_path`` should be a path that contains the root of a installation
-tree to be packaged. If you define a ``external_package_path`` of ``external``, it is assumed
+On Linux, the :attr:`external_package_path` should be a path that contains the root of a installation
+tree to be packaged. If you define an ``external_package_path`` of ``external``, it is assumed
 that ``external/usr/bin/<app_name>`` will be the executable for your application, which will
 be installed as ``/usr/bin/<app_name>``. Any other content that should be installed as
 part of your app should be included in the tree contained under ``external``.
 
-Although it is not possible to specify ``requires`` for external applications, external
-Linux applications *must* define ``system_runtime_requires``. These requirements are
+Although it is not possible to specify :attr:`requires` for external applications, external
+Linux applications *must* define :attr:`system_runtime_requires`. These requirements are
 used to define system-level requirements in the generated system packages.
 
 Windows
 ~~~~~~~
 
-On Windows, the ``external_package_path`` should be the directory that contains all the
+On Windows, the :attr:`external_package_path` should be the directory that contains all the
 content to be installed into the end-user's Program Files directory. By default, it is
 assumed that the executable used to launch the app is named
 ``<external_package_path>/<formal_name>.exe`` (or
 ``<external_package_path>/<app_name>.exe`` for a :doc:`console app </how-to/cli-apps>`).
 If this is not the name or path to your executable, you can define
-``external_package_executable_path`` to define the path inside ``external_package_path``
-to your executable binary. For example, a ``external_package_path`` value of
-``external``, and a ``external_package_executable_path`` value of
+:attr:`external_package_executable_path` to define the path inside ``external_package_path``
+to your executable binary. For example, an ``external_package_path`` value of
+``external``, and an ``external_package_executable_path`` value of
 ``somewhere/myapp.exe``, would define that ``external/somewhere/myapp.exe`` is the
 executable that should be installed as the application shortcut.
 
@@ -81,11 +81,11 @@ The files generated by the template should *not* be modified by hand. If you nee
 customize the contents of these templated files, you should use Briefcase app
 configuration settings to define those changes. For example, on macOS if you need to add
 an entitlement for signing purposes, you should *not* modify the templated
-``Entitlements.plist`` file by hand - you should use the :ref:`entitlement setting
-<macos-entitlement>` in your ``pyproject.toml``.
+``Entitlements.plist`` file by hand - you should use the :attr:`entitlement`
+setting in your ``pyproject.toml``.
 
 If Briefcase's configuration options are not sufficient for your requirements, you can
-either fork the template used by Briefcase and use the ``template`` option to point at
+either fork the template used by Briefcase and use the :attr:`template` option to point at
 your custom template; or you can :doc:`submit a pull request to Briefcase
 </how-to/contribute/code>` to support your customization use case.
 

docs/reference/commands/dev.rst

@@ -13,9 +13,9 @@ To run the app, run:
 
     $ briefcase dev
 
-The first time the application runs in developer mode, any requirements listed
-in a ``requires`` configuration item in ``pyproject.toml`` will be installed into
-the current environment.
+The first time the application runs in developer mode, any requirements listed in a
+:attr:`requires` configuration item in ``pyproject.toml`` will be installed into the
+current environment.
 
 Options
 =======

docs/reference/commands/index.rst

@@ -43,8 +43,8 @@ template=...``, but the value must be quoted::
 
     briefcase create -C template=\"https://example.com/template\"
 
-The only app key that *cannot* be overridden with ``-C`` is ``app_name``, as it is used
-to identify apps.
+The only app key that *cannot* be overridden with ``-C`` is :attr:`app_name`, as it is
+used to identify apps.
 
 ``-h`` / ``--help``
 -------------------

docs/reference/commands/run.rst

@@ -23,16 +23,16 @@ entry point will be used for the app: if your app is contained in a Python
 module named ``myapp``, test mode will attempt to launch ``tests.myapp``. Your
 app is responsible for providing the logic to discover and start the test suite.
 
-The code for your test suite can specified using the ``test_sources`` setting;
-test-specific requirements can be specified with ``test_requires``. Test sources
-and requirements will only be included in your app when running in test mode.
+The code for your test suite can specified using the :attr:`test_sources` setting;
+test-specific requirements can be specified with :attr:`test_requires`. Test sources and
+requirements will only be included in your app when running in test mode.
 
 Briefcase will monitor the log output of the test suite, looking for the output
-corresponding to test suite completion. Briefcase has built-in support for
-`pytest <https://docs.pytest.org/en/latest>`__ and `unittest
-<https://docs.python.org/3/library/unittest.html>`__ test suites; support for
-other test frameworks can be added using the ``test_success_regex`` and
-``test_failure_regex`` settings.
+corresponding to test suite completion. Briefcase has built-in support for `pytest
+<https://docs.pytest.org/en/latest>`__ and `unittest
+<https://docs.python.org/3/library/unittest.html>`__ test suites; support for other test
+frameworks can be added using the :attr:`test_success_regex` and
+:attr:`test_failure_regex` settings.
 
 Usage
 =====