Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
# Changelog

## Unreleased

### Added

- Options for customizing proof directive title format.

## v0.3.0 (2025-10-20)

### NEW ✨
Expand Down
57 changes: 55 additions & 2 deletions docs/source/options.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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`

Expand All @@ -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"
```
24 changes: 24 additions & 0 deletions sphinx_proof/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
9 changes: 9 additions & 0 deletions sphinx_proof/_static/minimal/proof.css
Original file line number Diff line number Diff line change
Expand Up @@ -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 *
*********************************************/
Expand Down
9 changes: 9 additions & 0 deletions sphinx_proof/_static/proof.css
Original file line number Diff line number Diff line change
Expand Up @@ -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 *
*********************************************/
Expand Down
4 changes: 3 additions & 1 deletion sphinx_proof/directive.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
6 changes: 3 additions & 3 deletions tests/conftest.py
Original file line number Diff line number Diff line change
@@ -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)

Expand Down