Minor adjustments

docs/ref/questions.md

@@ -19,7 +19,7 @@ Do not include the `saltext.` namespace here.
 :::{question} author
 :::
 ## `author`
-The author’s name for PyPI package metadata and licensing.
+The main author’s name for PyPI package metadata and licensing.
 
 **Example**: `Foo Bar`
 
@@ -141,6 +141,7 @@ Select a GitHub Actions workflow style:
 
 **enhanced**
 :  Equivalent workflows to `org`, but stored in the extension repository.
+   You need to [setup required secrets](required-secrets-target) yourself.
 
 **basic**
 :  Provided for compatibility with the deprecated create-salt-extension tool (not recommended for new projects).
@@ -166,7 +167,7 @@ Decide when to [publish documentation to GitHub pages](docs-publish-target):
    This ensures upcoming unreleased changes are displayed in the changelog.  
 
 :::{important}
-Ensure your GitHub Actions workflow is allowed to publish by setting `Pages` > `Build and deployment source` to `GitHub Actions` in your repository settings.
+Ensure your GitHub Actions workflow is [allowed to publish](docs-publish-setup-target) to your GitHub Pages site.
 :::
 
 :::{note}

docs/topics/extraction.md

@@ -39,7 +39,7 @@ The tool will:
 4. Auto-[cleanup the history](clean-history-target), as far as possible non-interactively
 5. [Run copier](populate-repo-target) with sane defaults and remove the project starter boilerplate
 6. [Create a virtual environment](migration-venv-target) for your project
-7. [Apply rewrites](migration-clean-up-target)
+7. [Apply rewrites](migration-clean-up-target) (with fixes and improvements versus `salt-rewrite`)
 8. Install and run pre-commit
 9. Provide an overview of issues to fix and next steps
 
@@ -73,7 +73,7 @@ cd salt
 git filter-repo --analyze
 tree .git/filter-repo/analysis/
 grep stalekey .git/filter-repo/analysis/path-{all,deleted}-sizes.txt | \
-    awk '{print $5}' | sort | uniq | \
+    awk '{print $NF}' | sort | uniq | \
     grep -vE '^(.github|doc/ref|debian/|doc/locale|salt/([^/]+/)?__init__.py|tests/(pytests/)?(unit|functional|integration)/conftest.py)'
 ```
 
@@ -236,14 +236,16 @@ references:
 
 :::{tab} old
 
-```python
-# ------- salt.modules.foo ---------------
+```{code-block} python
+:caption: salt/modules/foo.py
+
 def get(entity):
     return __utils__["foo.query"](entity)
 ```
 
-```python
-# ------- salt.utils.foo -----------------
+```{code-block} python
+:caption: salt/utils/foo.py
+
 def query(entity):
     base_url = __opts__.get("foo_base_url", "https://foo.bar")
     profile = __salt__["config.option"]("foo_profile")
@@ -252,17 +254,19 @@ def query(entity):
 :::
 
 :::{tab} correct
-```python
-# ------- saltext.foo.modules.foo -------
+```{code-block} python
+:caption: saltext/foo/modules/foo.py
+
 from saltext.foo.utils import foo
 
 
 def get(entity):
     base_url = __opts__.get("foo_base_url", "https://foo.bar")
     return foo.query(base_url, entity, __salt__["config.option"])
 ```
-```python
-# ------- saltext.foo.utils.foo -------
+```{code-block} python
+:caption: saltext/foo/utils/foo.py
+
 import salt.utils.http
 
 

docs/topics/publishing.md

@@ -25,7 +25,7 @@ git switch main && git fetch upstream && git rebase upstream/main
 ```
 
 (changelog-build-target)=
-## 1: Building the changelog
+## 1: Build the changelog
 
 Create and switch to a new branch:
 
@@ -41,15 +41,15 @@ towncrier build --yes --version v1.0.0
 
 This command combines all news fragments into {path}`CHANGELOG.md` and clears them. Commit the change.
 
-## 2: Submitting the changelog
+## 2: Submit the changelog
 
 Submit this commit as a PR and merge it into the default branch on `upstream`.
 
 :::{tip}
 Squash-merging this PR results in a cleaner tag target.
 :::
 
-## 3: Tagging a release
+## 3: Tag a release
 
 Ensure your `main` branch is up to date (again):
 
@@ -67,7 +67,7 @@ git tag v1.0.0
 The tag must start with `v` for the default publishing workflows to work correctly.
 :::
 
-## 4: Pushing the tag
+## 4: Push the tag
 
 Push the new tag upstream to trigger the publishing workflow: