Add options for proof directive title formatting (#163)

* Add options for proof directive title formatting

Introduces new configuration options: proof_title_format, proof_number_weight, and proof_title_weight, allowing users to customize the format and font weight of proof directive titles. Documentation and CSS updated to reflect these changes, and directive logic now applies the user-defined title format.

Author: douden

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- Options for customizing proof directive title format.
+
 ## v0.3.0 (2025-10-20)
 
 ### NEW ✨

docs/source/options.md

@@ -1,5 +1,7 @@
 # Options
 
+## Minimal color scheme
+
 This package has the option to choose a more **minimal** color scheme.
 
 The aim is to create admonitions that are clearly different to the core text with
@@ -15,7 +17,7 @@ compared to the current default
 
 To enable the `minimal` color scheme you can use the following.
 
-## Jupyter Book Project
+### Jupyter Book Project
 
 Add `proof_minimal_theme = True` to your `_config.yml`
 
@@ -25,6 +27,57 @@ sphinx:
     proof_minimal_theme: true
 ```
 
-## Sphinx Project
+### Sphinx Project
 
 Add `proof_minimal_theme = True` to your `conf.py`
+
+## Title format
+
+By default, the directive titles are formatted as `Name x.y.z (Title)`, where `Name` is the name of the directive (e.g., Proof, Theorem, Definition), `x.y.z` is the numbering of the directive, and `Title` is the optional title provided by the user.
+
+If no title is provided, only `Name x.y.z` is displayed.
+
+The font weight of the entire title (`Name x.y.z (Title)` or `Name x.y.z`) is set to `--pst-admonition-font-weight-heading` by default, which commonly results in a semi-bold appearance.
+
+In the reminder we call the part `Name x.y.z` the "number" and the part `(Title)` the "title".
+
+You can customize the title format using the `proof_title_format` option:
+
+- This option allows you to define how the title should be displayed by using `%t` as a placeholder for the user-provided title.
+- The default format is ` (%t)`.
+- A value of an empty string will result in no title being displayed.
+- A `markdown` string can be used to format the title.
+  - For example, ` *%t*` will emphasize the title and contain no brackets.
+
+Note that the initial part of the title (i.e., `Name x.y.z`) is not customizable and will always be displayed.
+
+The font weight of the title can be adjusted using the `proof_title_weight` option:
+
+- Any valid CSS font-weight value can be used, such as `normal`, `bold`, `bolder`, `lighter`, or numeric values like `400`, `700`, etc.
+- Default value is `var(--pst-admonition-font-weight-heading)`.
+
+The font weight of the number can be adjusted using the `proof_number_weight` option:
+- Any valid CSS font-weight value can be used, such as `normal`, `bold`, `bolder`, `lighter`, or numeric values like `400`, `700`, etc.
+- Default value is `var(--pst-admonition-font-weight-heading)`.
+
+### Jupyter Book Project
+
+Add `proof_title_format`, `proof_number_weight` and/or `proof_title_weight` to your `_config.yml`
+
+```yaml
+sphinx:
+  config:
+    proof_title_format: " *%t*"
+    proof_number_weight: "bold"
+    proof_title_weight: "normal"
+```
+
+### Sphinx Project
+
+Add `proof_title_format`, `proof_number_weight` and/or `proof_title_weight` to your `conf.py`
+
+```python
+proof_title_format = " *%t*"
+proof_number_weight = "bold"
+proof_title_weight = "normal"
+```

sphinx_proof/__init__.py

@@ -76,11 +76,35 @@ def copy_asset_files(app: Sphinx, exc: Union[bool, Exception]):
     if exc is None:
         for path in asset_files:
             copy_asset(path, str(Path(app.outdir).joinpath("_static").absolute()))
+            # if needed, load css to memory,
+            # adjust font-weight according to user's setting in config
+            # and write to output static file
+            if app.config.proof_number_weight or app.config.proof_title_weight:
+                # only if at least one of the two options is set
+                path = str(Path(app.outdir).joinpath("_static", "proof.css").absolute())
+                with open(path, "r", encoding="utf-8") as f:
+                    css_content = f.read()
+                if app.config.proof_number_weight:
+                    css_content = css_content.replace(
+                        "div.proof > p.admonition-title > span.caption-number {\n    font-weight: var(--pst-admonition-font-weight-heading);\n}",  # noqa: E501
+                        f"div.proof > p.admonition-title > span.caption-number {{\n    font-weight: {app.config.proof_number_weight};\n}}",  # noqa: E501
+                    )
+                if app.config.proof_title_weight:
+                    css_content = css_content.replace(
+                        "div.proof > p.admonition-title {\n    font-weight: var(--pst-admonition-font-weight-heading);\n}",  # noqa: E501
+                        f"div.proof > p.admonition-title {{\n    font-weight: {app.config.proof_title_weight};\n}}",  # noqa: E501
+                    )
+                out_path = Path(app.outdir).joinpath("_static", os.path.basename(path))
+                with open(out_path, "w", encoding="utf-8") as f:
+                    f.write(css_content)
 
 
 def setup(app: Sphinx) -> Dict[str, Any]:
 
     app.add_config_value("proof_minimal_theme", False, "html")
+    app.add_config_value("proof_title_format", " (%t)", "html")
+    app.add_config_value("proof_number_weight", "", "env")
+    app.add_config_value("proof_title_weight", "", "env")
 
     app.add_css_file("proof.css")
     app.connect("build-finished", copy_asset_files)

sphinx_proof/_static/minimal/proof.css

@@ -38,6 +38,15 @@ div.proof > .admonition-title::before {
 	content: none;
 }
 
+/* Set font weights */
+div.proof > p.admonition-title {
+    font-weight: var(--pst-admonition-font-weight-heading) !important;
+}
+
+div.proof > p.admonition-title > span.caption-number {
+    font-weight: var(--pst-admonition-font-weight-heading) !important;
+}
+
 /*********************************************
 * Proof *
 *********************************************/

sphinx_proof/_static/proof.css

@@ -23,6 +23,15 @@ div.proof p.admonition-title::before {
 	content: none;
 }
 
+/* Set font weights */
+div.proof > p.admonition-title {
+    font-weight: var(--pst-admonition-font-weight-heading);
+}
+
+div.proof > p.admonition-title > span.caption-number {
+    font-weight: var(--pst-admonition-font-weight-heading);
+}
+
 /*********************************************
 * Proof *
 *********************************************/

sphinx_proof/directive.py

@@ -66,7 +66,9 @@ def run(self) -> List[Node]:
 
         title_text = ""
         if self.arguments != []:
-            title_text += f" ({self.arguments[0]})"
+            title_format = self.config.proof_title_format
+            title_text += title_format.replace("%t", self.arguments[0])
+            # title_text += f" ({self.arguments[0]})"
 
         textnodes, messages = self.state.inline_text(title_text, self.lineno)
 

tests/conftest.py

@@ -1,17 +1,17 @@
 import shutil
 import pytest
 
-from sphinx.testing.path import path
+from pathlib import Path
 
 pytest_plugins = "sphinx.testing.fixtures"
 
 
 @pytest.fixture
 def rootdir(tmpdir):
-    src = path(__file__).parent.abspath() / "books"
+    src = Path(__file__).parent / "books"
     dst = tmpdir.join("books")
     shutil.copytree(src, dst)
-    books = path(dst)
+    books = Path(dst)
     yield books
     shutil.rmtree(dst)