SFDO-Tooling · jstvz · Apr 9, 2025 · Apr 3, 2025
@@ -7,16 +7,16 @@ changelog:
         authors:
             - app/github-actions
     categories:
-        - title: Critical Changes 🛠
+        - title: Critical Changes
           labels:
               - critical-change
-        - title: Changes 🎉
+        - title: Changes
           labels:
               - enhancement
               - "*"
           exclude:
               labels:
                   - bug
-        - title: Issues Fixed 🩴
+        - title: Issues Fixed
           labels:
               - bug
@@ -27,3 +27,7 @@ sphinx:
 formats:
     - pdf
     - epub
+  # Optionally declare the Python requirements required to build your docs
+# python:
+#     install:
+#         - requirements: requirements_dev.txt
@@ -3,6 +3,6 @@
 ```{toctree}
 :maxdepth: 1
 
-history
 contributing
-```
+history
+```
@@ -100,6 +100,10 @@
 # directories to ignore when looking for source files.
 exclude_patterns = ["_build", "*/tests/"]
 
+# Exclude 'history.md' only in LaTeX builds
+if os.environ.get("SPHINX_OUTPUT_FORMAT") == "latex":
+    exclude_patterns.append("history.md")
+
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
 # default_role = None
@@ -222,21 +226,22 @@
 # This is the file name suffix for HTML files (e.g. ".xhtml").
 # html_file_suffix = None
 
+suppress_warnings = ["ref.duplicate_label"]
+
 # Output file base name for HTML help builder.
 htmlhelp_basename = "cumuluscidoc"
 
 
 # -- Options for LaTeX output ------------------------------------------
+latex_engine = "xelatex"
+
 
 latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    # 'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    # 'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    # 'preamble': '',
+    'preamble': r'''\renewcommand{\familydefault}{\sfdefault}  % Set default font to sans-serif
+''',
 }
 
+
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).
@@ -245,13 +250,16 @@
         "index",
         "cumulusci.tex",
         "CumulusCI Documentation",
-        """Kamalnath Devarakonda\\\\
-Sr Director Software Engineering\\\\
-kdevarakonda@salesforce.com""",
+        r"""
+        \parbox{\textwidth}{\raggedleft
+        {\fontsize{15}{12} Kamalnath Devarakonda}\\
+        {\fontsize{14}{12}\selectfont Sr. Director, Software Engineering}\\
+        {\fontsize{13}{12}\selectfont kdevarakonda@salesforce.com}
+        }
+        """,
         "manual",
     )
 ]
-
 # The name of an image file (relative to this directory) to place at
 # the top of the title page.
 # latex_logo = None

@@ -86,7 +86,7 @@ Options
     Require at least X percent code coverage across the org following the test run.
     Default: 90
 ```
-
+(add-a-custom-task)=
 ### Add a Custom Task
 
 To define a new task for your project, add the task name under the
@@ -534,7 +534,7 @@ will fetch the most recent production release, or the default branch if
 there are no releases. By specifying `resolution_strategy`, the behavior
 can be changed to match desired dependency resolution behavior, such as
 using beta releases or retrieving feature test packages from a commit
-status. See [](dependency-resolution) for
+status. See [](controlling-github-dependency-resolution) for
 more details about resolution strategies.
 
 ```{note}
@@ -723,7 +723,7 @@ in your cumulusci.yml file.
 
 ### Customizing Metadata Deployment
 
-CumulusCI's `deploy` task offers deep flexibility to customize your deployment process. Review [](deploy) for an in-depth guide.
+CumulusCI's `deploy` task offers deep flexibility to customize your deployment process. Review [](configure-metadata-deployment) for an in-depth guide.
 
 ```{toctree}
 ---

@@ -65,26 +65,22 @@ CumulusCI with the name `devhub`.
 
 ```console
 $ cci org list
+                         Scratch Orgs
+
+  Default   Name         Days   Expired   Config       Domain
+ ─────────────────────────────────────────────────────────────
+            beta         1                beta
+            dev          7      ✔         dev
+            feature      1                feature
+            qa           7      ✔         qa
+            release      1                release
+
+                                     Connected Orgs
+
+  Default   Name                 Username                                    Expires
+ ───────────────────────────────────────────────────────────────────────────────────────
+            devhub       j.holt@mydomain.devhub                    Persistent
 
-┌Scratch Orgs──────────────┬─────────┬──────┬─────────┬──────────────┬────────┐
-│ Name                     │ Default │ Days │ Expired │ Config       │ Domain │
-├──────────────────────────┼─────────┼──────┼─────────┼──────────────┼────────┤
-│ dev                      │         │ 7    │ X       | dev          │        │
-├──────────────────────────┼─────────┼──────┼─────────┼──────────────┼────────┤
-│ feature                  │         │ 1    │ X       | feature      │        │
-├──────────────────────────┼─────────┼──────┼─────────┼──────────────┼────────┤
-│ prerelease               │         │ 1    │ X       | prerelease   │        │
-├──────────────────────────┼─────────┼──────┼─────────┼──────────────┼────────┤
-│ qa                       │         │ 7    │ X       | qa           │        │
-├──────────────────────────┼─────────┼──────┼─────────┼──────────────┼────────┤
-│ release                  │         │ 1    │ X       | release      │        │
-└──────────────────────────┴─────────┴──────┴─────────┴──────────────┴────────┘
-
-┌Connected Orgs────┬──────────────────────────────┬────────────┐
-│ Name   │ Default │ Username                     │ Expires    │
-├────────┼─────────┼──────────────────────────────┼────────────┤
-│ devhub │         │ j.holt@mydomain.devhub       │ Persistent │
-└────────┴─────────┴──────────────────────────────┴────────────┘
 ```
 
 Verify a successful connection to the org by logging in.

@@ -50,7 +50,7 @@ variables to provide access to orgs and services [in a headless context](headles
 
 CumulusCI makes it easy to harness the power of second-generation
 managed packages to implement an advanced, comprehensive testing process
-for both first- and second-generation managed package products. This is
+for both first-generation and second-generation managed package products. This is
 described in [](2gp-testing).
 
 ## Further Reading

@@ -295,6 +295,7 @@ child branches. This means that despite
 `feature/large-feature__section1` having two child branches, they would
 not receive automerges until the parent branch tests successfully.
 
+(release-to-future-release-merges)=
 ### Release to (Future) Release Merges
 
 Because release branches are so long-lived, and so much work goes into

@@ -26,7 +26,7 @@ For example, the 'dev' dataset is for 'dev' orgs, and it is used
 instead of the default dataset if it exists.
 
 You can create a dataset by extracting data from an existing org
-or by authoring a [Snowfakery recipe](Generate-Fake-Data).
+or by authoring a [Snowfakery recipe](#generate-fake-data).
 Extracting from an existing org is easy for use-cases where the
 data already exists or can be readily created in an org. Snowfakery
 is better for cases where either a) you would like to dynamically
@@ -37,14 +37,14 @@ A Snowfakery dataset can consist of a single file with a name like
 `datasets/<datasetname>/<datasetname>.recipe.yml` . For example,
 `datasets/default/default.recipe.yml` or
 `datasets/qa/qa.recipe.yml`. The rest of what you need to know
-about Snowfakery is in the section [Generate Fake Data](Generate-Fake-Data).
+about Snowfakery is in the section [Generate Fake Data](#generate-fake-data).
 
 ### Extracting and Loading Sample Datasets
 
 In the simplest case, you can extract all data from an org
 using the task `capture_sample_data` like this:
 
-```s
+```console
 $ cci task run capture_sample_data --org orgname
 ```
 
@@ -54,7 +54,7 @@ org named `orgname` into the dataset named `default`.
 You can then load it into any target org (e.g.
 `org2`) like this:
 
-```s
+```console
 $ cci task run load_sample_data --org org2
 ```
 
@@ -88,11 +88,11 @@ If you want different datasets for different scratch org types
 loaded by those types by making datasets specific to each one.
 This data will load instead of the default dataset.
 
-```s
+```console
 $ cci task run capture_sample_data --dataset dev --org org1
 ```
 
-```s
+```console
 $ cci task run capture_sample_data --dataset qa --org org2
 ```
 
@@ -816,11 +816,13 @@ Extract the data for a dataset from an org and persist it to disk.
 
 `mapping` and either `sql_path` or `database_url` must be supplied.
 
-Example: :
-
-    cci task run extract_dataset -o mapping datasets/qa/mapping.yml -o sql_path datasets/qa/data.sql --org qa
+Example: 
+```console
+cci task run extract_dataset -o mapping datasets/qa/mapping.yml -o sql_path datasets/qa/data.sql --org qa
+```
 
-### <a name="data-load-dataset"></a> `load_dataset`
+(data-load-dataset)=
+###  `load_dataset`
 
 Load the data for a dataset into an org. If the storage is a database,
 persist new Salesforce Ids to storage.
@@ -840,9 +842,11 @@ persist new Salesforce Ids to storage.
 
 `mapping` and either `sql_path` or `database_url` must be supplied.
 
-Example: :
+Example: 
 
-    cci task run load_dataset -o mapping datasets/qa/mapping.yml -o sql_path datasets/qa/data.sql --org qa
+```console
+cci task run load_dataset -o mapping datasets/qa/mapping.yml -o sql_path datasets/qa/data.sql --org qa
+```
 
 ### `generate_dataset_mapping`
 
@@ -908,9 +912,11 @@ after their target records become available.
 -   `namespace_prefix`: The namespace prefix to treat as belonging to
     the project, if any
 
-Example: :
+Example: 
 
-    cci task run generate_dataset_mapping --org qa -o namespace_prefix my_ns
+```console
+cci task run generate_dataset_mapping --org qa -o namespace_prefix my_ns
+```
 
 ### `load_custom_settings`
 
@@ -994,6 +1000,8 @@ option:
 
 You can learn more about Snowfakery syntax in the next section.
 
+(Generate-Fake-Data)=
+
 ## Generate Fake Data
 
 It is possible to use CumulusCI to generate arbitrary amounts of

@@ -11,7 +11,7 @@ generated by `capture_sample_data` or by Metecho.
 
 An extract declaration looks like this:
 
-```yml
+```yaml
 extract:
     Opportunity:
         fields:
@@ -27,7 +27,7 @@ and Account.
 
 That declaration is therefore the same as:
 
-```yml
+```yaml
 # This will download the Salesforce-y trinity
 # of Accounts, Contacts and Opportunities
 extract:

@@ -1,3 +1,4 @@
+(configure-metadata-deployment)=
 # Configure Metadata Deployment
 
 CumulusCI's `deploy` task uses the Metadata API to deploy metadata from the repository to a Salesforce org. `deploy` offers multiple sophisticated capabilities to suit the needs of your project.
@@ -62,7 +63,7 @@ flows:
                                 replace: bar
 ```
 
-To learn more about customization, see [](config). To discover the available transform options, consult the section for each transform in [](deploy).
+To learn more about customization, see [](config). To discover the available transform options, consult the section for each transform in [](configure-metadata-deployment).
 
 ### Namespace Injection
 

@@ -61,8 +61,7 @@ The [](retrieve-changes) task supports both
 Salesforce DX and Metadata API-format source code. It utilizes the
 [SourceMember](https://developer.salesforce.com/docs/atlas.en-us.api_tooling.meta/api_tooling/tooling_api_objects_sourcemember.htm)
 `sObject` to detect what has changed in an org, and also gives you
-discretion regarding which components are retrieved when compared to the
-[](dx-pull) task.
+discretion regarding which components are retrieved.
 
 To retrieve _all_ changes in an org:
 
@@ -161,23 +160,16 @@ code and metadata stored in the repository. After making changes in an
 editor, push these changes from your project's local repository to the
 target org.
 
-If your project uses the Salesforce DX source format, use the
-[](dx-push) task.
-
-```console
-$ cci task run dx_push
-```
-
-If your project uses the Metadata API source format, use the
-[](deploy) task:
+To push your changes, use the
+[deploy](configure-metadata-deployment) task:
 
 ```console
 $ cci task run deploy
 ```
 
 The `deploy` task has _many_ options for handling a number of different
 scenarios. For a comprehensive list of options, see the
-[](deploy) task reference.
+[deploy](configure-metadata-deployment) task reference.
 
 ## Run Apex Tests
 

@@ -26,6 +26,7 @@ OS keychain is not available.
 Used for specifying a GitHub Repository for CumulusCI to use when
 running in a CI environment.
 
+(cumulusci-system-certs)=
 ## `CUMULUSCI_SYSTEM_CERTS`
 
 If set to `True`, CumulusCI will configure the Python `requests` library
@@ -42,6 +43,7 @@ Your GitHub App's identifier.
 Contents of a JSON Web Token (JWT) used to [authenticate a GitHub
 app](https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/##authenticating-as-a-github-app).
 
+(github-token)=
 ## `GITHUB_TOKEN`
 
 A GitHub [personal access

@@ -122,6 +122,7 @@ pipx install cumulusci
 
 When finished, [verify your installation](verify-your-installation).
 
+(update-environment-variables-manually)=
 #### Update Environment Variables Manually
 
 1.  Click Start and search for `edit environment variables`, or open

@@ -86,7 +86,7 @@ then the attributes: `callback_url`, `client_id`, and `client_secret`
 would need to be provided in the following format:
 
 ```json
-"{"callback_url": "<callback_url>", "client_id": "<client_id>", "client_secret": "<client_secret>"}"
+{"callback_url": "<callback_url>", "client_id": "<client_id>", "client_secret": "<client_secret>"}
 ```
 
 > The values `<callback_url>`, `<client_id>`, and `<client_secret>`