Merge pull request #1257 from ferdnyc/patch-1

docs: Fix list & code block formatting on RtD

Author: RonnyPfannschmidt

docs/config.md

@@ -231,12 +231,14 @@ Callables or other Python objects have to be passed in `setup.py` (via the `use_
 3. Works for `include_package_data = True` in package building
 
 **Entry point registration:**
+
 ```toml
 [project.entry-points."setuptools.file_finders"]
 setuptools_scm = "setuptools_scm._file_finders:find_files"
 ```
 
 **Files included by default:**
+
 - All files tracked by Git (`git ls-files`)
 - All files tracked by Mercurial (`hg files`)
 - Includes: source code, documentation, tests, config files, etc.
@@ -290,6 +292,7 @@ tar -tzf dist/package-*.tar.gz
 
 
 ### the configuration class
+
 ::: setuptools_scm.Configuration
     options:
       heading_level: 4

docs/extending.md

@@ -44,6 +44,7 @@
 
 
 ### `setuptools_scm.version_scheme`
+
 Configures how the version number is constructed given a
 [ScmVersion][setuptools_scm.version.ScmVersion] instance and should return a string
 representing the version.
@@ -58,6 +59,7 @@ representing the version.
     and custom `.devN` versions will trigger an error.
 
     **Examples:**
+
     - Tag `v1.0.0` → version `1.0.1.dev0` (if dirty or distance > 0)
     - Tag `v1.0.0` → version `1.0.0` (if exact match)
 
@@ -69,6 +71,7 @@ representing the version.
     for release branches.
 
     **Examples:**
+
     - Tag `v23.01.15.0` on same day → version `23.01.15.1.devN`
     - Tag `v23.01.15.0` on different day (e.g., 2023-01-16) → version `23.01.16.0.devN`
     - Tag `v2023.01.15.0` → uses 4-digit year format for new versions
@@ -78,6 +81,7 @@ representing the version.
     This is the recommended replacement for the deprecated `post-release` scheme.
 
     **Examples:**
+
     - Tag `v1.0.0` → version `1.0.0.post1.devN` (if distance > 0)
     - Tag `v1.0.0` → version `1.0.0` (if exact match)
 
@@ -87,6 +91,7 @@ representing the version.
     !!! warning "This means version is no longer pseudo unique per commit"
 
     **Examples:**
+
     - Tag `v1.0.0` → version `1.0.0` (always, regardless of distance or dirty state)
 
 `post-release (deprecated)`
@@ -97,6 +102,7 @@ representing the version.
     !!! warning "the recommended replacement is `no-guess-dev`"
 
     **Examples:**
+
     - Tag `1.0.0` → version `1.0.0.postN` (where N is the distance)
 
 `python-simplified-semver`
@@ -109,6 +115,7 @@ representing the version.
     This scheme is not compatible with pre-releases.
 
     **Examples:**
+
     - Tag `1.0.0` on non-feature branch → version `1.0.1.devN`
     - Tag `1.0.0` on feature branch → version `1.1.0.devN`
 
@@ -123,12 +130,15 @@ representing the version.
     Namespaces are unix pathname separated parts of a branch/tag name.
 
     **Examples:**
+
     - Tag `1.0.0` on release branch `release-1.0` → version `1.0.1.devN`
 
     - Tag `1.0.0` on release branch `release/v1.0` → version `1.0.1.devN`
+
     - Tag `1.0.0` on development branch → version `1.1.0.devN`
 
 ### `setuptools_scm.local_scheme`
+
 Configures how the local part of a version is rendered given a
 [ScmVersion][setuptools_scm.version.ScmVersion] instance and should return a string
 representing the local version.

docs/integrations.md

@@ -60,6 +60,7 @@ setuptools-scm provides the `no-local-version` local scheme and environment vari
 #### The Problem
 
 By default, setuptools-scm generates version numbers like:
+
 - `1.2.3.dev4+g1a2b3c4d5` (development version with git hash)
 - `1.2.3+dirty` (dirty working directory)
 
@@ -72,6 +73,7 @@ Use the `SETUPTOOLS_SCM_OVERRIDES_FOR_${DIST_NAME}` environment variable to over
 ### GitHub Actions Example
 
 Here's a complete GitHub Actions workflow that:
+
 - Runs tests on all branches
 - Uploads development versions to test-PyPI from feature branches
 - Uploads development versions to PyPI from the main branch (with no-local-version)
@@ -290,9 +292,10 @@ publish-release:
 The environment variable `SETUPTOOLS_SCM_OVERRIDES_FOR_${DIST_NAME}` must be set where:
 
 1. **`${DIST_NAME}`** is your package name normalized according to PEP 503:
-   - Convert to uppercase
-   - Replace hyphens and dots with underscores
-   - Examples: `my-package` → `MY_PACKAGE`, `my.package` → `MY_PACKAGE`
+
+    - Convert to uppercase
+    - Replace hyphens and dots with underscores
+    - Examples: `my-package` → `MY_PACKAGE`, `my.package` → `MY_PACKAGE`
 
 2. **Value** must be a valid TOML inline table format:
    ```bash
@@ -316,10 +319,12 @@ However, the environment variable approach is preferred for CI/CD as it allows d
 #### Version Examples
 
 **Development versions from main branch** (with `local_scheme = "no-local-version"`):
+
 - Development commit: `1.2.3.dev4+g1a2b3c4d5` → `1.2.3.dev4` ✅ (uploadable to PyPI)
 - Dirty working directory: `1.2.3+dirty` → `1.2.3` ✅ (uploadable to PyPI)
 
 **Tagged releases** (without overrides, using default local scheme):
+
 - Tagged commit: `1.2.3` → `1.2.3` ✅ (uploadable to PyPI)
 - Tagged release on dirty workdir: `1.2.3+dirty` → `1.2.3+dirty` ❌ (should not happen in CI)
 

docs/usage.md

@@ -26,12 +26,14 @@ dynamic = ["version"]
 ```
 
 This streamlined approach automatically enables version inference when:
+
 - `setuptools-scm[simple]` is listed in `build-system.requires`
 - `version` is included in `project.dynamic`
 
 !!! tip "When to use simplified activation"
 
     Use simplified activation when you:
+
     - Want basic SCM version inference with default settings
     - Don't need custom version schemes or file writing
     - Prefer minimal configuration
@@ -90,6 +92,7 @@ Version files can be created with the ``version_file`` directive.
 [tool.setuptools_scm]
 version_file = "pkg/_version.py"
 ```
+
 Where ``pkg`` is the name of your package.
 
 Unless the small overhead of introspecting the version at runtime via
@@ -253,6 +256,7 @@ without copying the entire `.git` folder into the container image.
 RUN --mount=source=.git,target=.git,type=bind \
     pip install --no-cache-dir -e .
 ```
+
 However, this build step introduces a dependency to the state of your local
 `.git` folder the build cache and triggers the long-running pip install process on every build.
 To optimize build caching, one can use an environment variable to pretend a pseudo
@@ -332,6 +336,7 @@ setuptools-scm's default tag regex supports:
 - **Build metadata**: Anything after `+` is ignored
 
 **Examples of valid tags:**
+
 ```bash
 # Recommended formats (with v prefix)
 v1.0.0
@@ -390,6 +395,7 @@ The prefixes are automatically added by setuptools-scm and should be included wh
 specifying node IDs in environment variables like `SETUPTOOLS_SCM_PRETEND_METADATA`.
 
 **Examples:**
+
 ```bash
 # Git node ID
 1.0.0.dev5+g1a2b3c4d5
@@ -448,14 +454,16 @@ $ python -m setuptools_scm create-archival-file --full
 Alternatively, you can create the file manually:
 
 **Stable version (recommended):**
-```{ .text file=".git_archival.txt"}
+
+```{ .text title=".git_archival.txt"}
 node: $Format:%H$
 node-date: $Format:%cI$
 describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$
 ```
 
 **Full version (with branch information - can cause instability):**
-```{ .text file=".git_archival.txt"}
+
+```{ .text title=".git_archival.txt"}
 # WARNING: Including ref-names can make archive checksums unstable
 # after commits are added post-release. Use only if describe-name is insufficient.
 node: $Format:%H$
@@ -475,11 +483,12 @@ tagging style.
     post-release. See [this issue][git-archive-issue] for more details.
 
 
-``` {.text file=".gitattributes"}
+``` {.text title=".gitattributes"}
 .git_archival.txt  export-subst
 ```
 
 Finally, commit both files:
+
 ```commandline
 $ git add .git_archival.txt .gitattributes && git commit -m "add git archive support"
 ```
@@ -488,7 +497,7 @@ $ git add .git_archival.txt .gitattributes && git commit -m "add git archive sup
 
 If you see warnings like these when building your package:
 
-```
+```text
 UserWarning: git archive did not support describe output
 UserWarning: unprocessed git archival found (no export subst applied)
 ```
@@ -503,7 +512,7 @@ This typically happens when:
 **For development builds:**
 Exclude `.git_archival.txt` from your package to avoid warnings:
 
-```{ .text file="MANIFEST.in"}
+```{ .text title="MANIFEST.in"}
 # Exclude archival file from development builds
 exclude .git_archival.txt
 ```
@@ -526,14 +535,15 @@ Many CI systems and package repositories (like GitHub Actions) automatically han
 #### Integration with package managers
 
 **MANIFEST.in exclusions:**
-```{ .text file="MANIFEST.in"}
+
+```{ .text title="MANIFEST.in"}
 # Exclude development files from packages
 exclude .git_archival.txt
 exclude .gitattributes
 ```
 
 
-```{ .text file=".gitattributes"}
+```{ .text title=".gitattributes"}
 # Archive configuration
 .git_archival.txt  export-subst
 .gitignore         export-ignore
@@ -542,14 +552,17 @@ exclude .gitattributes
 #### Troubleshooting
 
 **Problem: "unprocessed git archival found" warnings**
+
 - ✅ **Solution**: Add `exclude .git_archival.txt` to `MANIFEST.in` for development builds
 - ✅ **Alternative**: Build from actual git archives for releases
 
 **Problem: "git archive did not support describe output" warnings**
+
 - ℹ️ **Information**: This is expected when `.git_archival.txt` contains unexpanded templates
 - ✅ **Solution**: Same as above - exclude file or build from git archives
 
 **Problem: Version detection fails in git archives**
+
 - ✅ **Check**: Is `.gitattributes` configured with `export-subst`?
 - ✅ **Check**: Are you building from a properly created git archive?
 - ✅ **Check**: Does your git hosting provider support archive template expansion?
@@ -561,7 +574,8 @@ exclude .gitattributes
 !!! note "Version Files"
 
     If you are creating a `_version.py` file, it should not be kept in version control. Add it to `.gitignore`:
-    ```
+
+    ```{.ini title=".gitignore"}
     # Generated version file
     src/mypackage/_version.py
     ```
@@ -594,31 +608,36 @@ would be required when not using `setuptools-scm`.
 **To exclude unwanted files:**
 
 1. **Use `MANIFEST.in`** to exclude specific files/patterns:
-   ```
-   exclude development.txt
-   recursive-exclude tests *.pyc
-   ```
+
+    ```{.text title="MANIFEST.in"}
+    exclude development.txt
+    recursive-exclude tests *.pyc
+    ```
 
 2. **Configure Git archive** (for Git repositories):
-   ```bash
-   # Add to .gitattributes
-   tests/ export-ignore
-   *.md export-ignore
-   ```
+
+    ```{.bash title=".gitattributes"}
+    # Add to .gitattributes
+    tests/ export-ignore
+    *.md export-ignore
+    ```
 
 3. **Use `.hgignore`** or **Mercurial archive configuration** (for Mercurial repositories)
 
 #### Troubleshooting
 
 **Problem: Unwanted files in my package**
+
 - ✅ **Solution**: Add exclusions to `MANIFEST.in`
 - ✅ **Alternative**: Use Git/Mercurial archive configuration
 
 **Problem: Missing files in package**
+
 - ✅ **Check**: Are the files tracked in your SCM?
 - ✅ **Solution**: `git add` missing files or override with `MANIFEST.in`
 
 **Problem: File finder not working**
+
 - ✅ **Check**: Is setuptools-scm installed in your build environment?
 - ✅ **Check**: Are you in a valid SCM repository?