diff --git a/.github/workflows/test-formats.yml b/.github/workflows/test-formats.yml index e000c6c0..d5727f29 100644 --- a/.github/workflows/test-formats.yml +++ b/.github/workflows/test-formats.yml @@ -18,11 +18,11 @@ jobs: format: ["man", "text"] steps: - - uses: actions/checkout@v4 - - name: Set up Python 3.10 - uses: actions/setup-python@v5 + - uses: actions/checkout@v6 + - name: Set up Python 3.11 + uses: actions/setup-python@v6 with: - python-version: "3.10" + python-version: "3.11" - name: Install dependencies run: | python -m pip install --upgrade pip @@ -42,11 +42,11 @@ jobs: format: ["latex"] steps: - - uses: actions/checkout@v4 - - name: Set up Python 3.10 - uses: actions/setup-python@v5 + - uses: actions/checkout@v6 + - name: Set up Python 3.11 + uses: actions/setup-python@v6 with: - python-version: "3.10" + python-version: "3.11" - name: Install dependencies run: | python -m pip install --upgrade pip diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index a49f4c4b..f68f84dd 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -13,11 +13,11 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - name: Set up Python 3.10 - uses: actions/setup-python@v5 + - uses: actions/checkout@v6 + - name: Set up Python 3.11 + uses: actions/setup-python@v6 with: - python-version: "3.10" + python-version: "3.11" - uses: pre-commit/action@v3.0.1 tests: @@ -25,25 +25,25 @@ jobs: strategy: fail-fast: false matrix: - python-version: ["3.10", "3.11", "3.12", "3.13"] - sphinx: [">=8,<9"] + python-version: ["3.11", "3.12", "3.13", "3.14"] + sphinx: [">=8,<9", ">=9,<10"] os: [ubuntu-latest] include: - - os: ubuntu-latest - python-version: "3.10" - sphinx: ">=7,<8" - os: windows-latest - python-version: "3.10" - sphinx: ">=7,<8" + python-version: "3.11" + sphinx: ">=8,<9" + - os: windows-latest + python-version: "3.14" + sphinx: ">=9,<10" runs-on: ${{ matrix.os }} name: "pytest: py${{ matrix.python-version }}, sphinx${{ matrix.sphinx }}, on ${{ matrix.os }}" steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v6 - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v5 + uses: actions/setup-python@v6 with: python-version: ${{ matrix.python-version }} allow-prereleases: true @@ -52,18 +52,19 @@ jobs: python -m pip install --upgrade pip pip install -e ".[linkify,testing]" "sphinx${{ matrix.sphinx }}" - name: Run pytest - run: | - pytest --cov=myst_parser --cov-report=xml --cov-report=term-missing - coverage xml - - name: Upload to Codecov - if: github.repository == 'executablebooks/MyST-Parser' && matrix.python-version == 3.10 && matrix.os == 'ubuntu-latest' - uses: codecov/codecov-action@v4 - with: - token: ${{ secrets.CODECOV_TOKEN }} - name: myst-parser-pytests - flags: pytests - file: ./coverage.xml - fail_ci_if_error: true + run: pytest --cov=myst_parser --cov-report=xml --cov-report=term-missing + - name: Create coverage report + run: coverage xml + # TODO there is currently problem with this action and pull-requests from external forks + # - name: Upload to Codecov + # if: github.repository == 'executablebooks/MyST-Parser' && matrix.python-version == 3.11 && matrix.os == 'ubuntu-latest' + # uses: codecov/codecov-action@v4 + # with: + # token: ${{ secrets.CODECOV_TOKEN }} + # name: myst-parser-pytests + # flags: pytests + # file: ./coverage.xml + # fail_ci_if_error: true check-myst-docutils: @@ -73,15 +74,15 @@ jobs: strategy: fail-fast: false matrix: - docutils-version: ["0.19", "0.20", "0.21"] + docutils-version: ["0.20", "0.21", "0.22"] steps: - name: Checkout source - uses: actions/checkout@v4 - - name: Set up Python 3.10 - uses: actions/setup-python@v5 + uses: actions/checkout@v6 + - name: Set up Python 3.11 + uses: actions/setup-python@v6 with: - python-version: "3.10" + python-version: "3.11" - name: Install setup run: | python -m pip install --upgrade pip @@ -132,11 +133,11 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout source - uses: actions/checkout@v4 - - name: Set up Python 3.10 - uses: actions/setup-python@v5 + uses: actions/checkout@v6 + - name: Set up Python 3.11 + uses: actions/setup-python@v6 with: - python-version: "3.10" + python-version: "3.11" - name: install flit run: | pip install flit~=3.4 @@ -155,11 +156,11 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout source - uses: actions/checkout@v4 - - name: Set up Python 3.10 - uses: actions/setup-python@v5 + uses: actions/checkout@v6 + - name: Set up Python 3.11 + uses: actions/setup-python@v6 with: - python-version: "3.10" + python-version: "3.11" - name: install flit and tomlkit run: | pip install flit~=3.4 tomlkit diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0504ee84..16e470fd 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -13,7 +13,7 @@ exclude: > repos: - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v5.0.0 + rev: v6.0.0 hooks: - id: check-json - id: check-yaml @@ -21,22 +21,22 @@ repos: - id: trailing-whitespace - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.8.4 + rev: v0.14.11 hooks: - - id: ruff + - id: ruff-check args: [--fix] - id: ruff-format - repo: https://github.com/pre-commit/mirrors-mypy - rev: v1.14.0 + rev: v1.19.1 hooks: - id: mypy args: [--config-file=pyproject.toml] additional_dependencies: - types-urllib3 - - sphinx~=7.4 - - markdown-it-py~=3.0 - - mdit-py-plugins~=0.4.0 + - sphinx~=8.2 + - markdown-it-py~=4.0 + - mdit-py-plugins~=0.5.0 files: > (?x)^( myst_parser/.*py| diff --git a/.readthedocs.yml b/.readthedocs.yml index cb68e005..f166afb7 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -3,7 +3,7 @@ version: 2 build: os: ubuntu-22.04 tools: - python: "3.10" + python: "3.11" python: install: diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..2851b1d5 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,343 @@ +# AGENTS.md + +This file provides guidance for AI coding agents working on the **MyST-Parser** repository. + +## Project Overview + +MyST-Parser is a Sphinx extension and docutils parser for the MyST (Markedly Structured Text) Markdown flavor. It provides: + +- An extended [CommonMark](https://commonmark.org)-compliant parser using [`markdown-it-py`](https://markdown-it-py.readthedocs.io/) +- A [docutils](https://docutils.sourceforge.io/) renderer that converts markdown-it tokens to docutils nodes +- A [Sphinx](https://www.sphinx-doc.org) extension for using MyST Markdown in Sphinx documentation + +MyST is designed for technical documentation and publishing, offering a rich and extensible flavor of Markdown with support for roles, directives, and cross-references. + +## Repository Structure + +``` +pyproject.toml # Project configuration and dependencies +tox.ini # Tox test environment configuration + +myst_parser/ # Main source code +├── __init__.py # Package init with Sphinx setup() entry point +├── config/ # Configuration dataclasses +│ ├── main.py # MdParserConfig dataclass +│ └── dc_validators.py # Dataclass field validators +├── parsers/ # Parser implementations +│ ├── sphinx_.py # Sphinx parser (MystParser) +│ ├── docutils_.py # Docutils parser and CLI tools +│ ├── mdit.py # markdown-it-py setup and plugins +│ ├── directives.py # Directive parsing utilities +│ └── options.py # Option parsing for directives +├── mdit_to_docutils/ # Token-to-docutils rendering +│ ├── base.py # DocutilsRenderer (main renderer) +│ ├── sphinx_.py # SphinxRenderer (Sphinx-specific) +│ ├── transforms.py # Docutils transforms +│ └── html_to_nodes.py # HTML-to-docutils conversion +├── sphinx_ext/ # Sphinx extension components +│ ├── main.py # setup_sphinx() and config creation +│ ├── directives.py # Custom Sphinx directives +│ ├── myst_refs.py # Reference resolver post-transform +│ └── mathjax.py # MathJax configuration +├── inventory.py # Sphinx inventory file handling +├── mocking.py # Mock objects for directive/role parsing +├── warnings_.py # Warning types (MystWarnings enum) +├── cli.py # Command-line interface +└── _compat.py # Python version compatibility + +tests/ # Test suite +├── test_sphinx/ # Sphinx integration tests +│ ├── sourcedirs/ # Test documentation projects +│ └── test_sphinx_builds.py +├── test_renderers/ # Renderer unit tests +├── test_commonmark/ # CommonMark compliance tests +├── test_html/ # HTML output tests +├── test_docutils.py # Docutils parser tests +└── test_anchors.py # Heading anchor tests + +docs/ # Documentation source (MyST Markdown) +├── conf.py # Sphinx configuration +├── index.md # Documentation index +├── syntax/ # Syntax reference documentation +├── develop/ # Developer documentation +└── faq/ # FAQ and troubleshooting +``` + +## Development Commands + +All commands should be run via [`tox`](https://tox.wiki) for consistency. The project uses `tox-uv` for faster environment creation. + +### Testing + +```bash +# Run all tests +tox + +# Run a specific test file +tox -- tests/test_docutils.py + +# Run a specific test function +tox -- tests/test_docutils.py::test_function_name + +# Run tests with a specific Python/Sphinx version +tox -e py311-sphinx8 + +# Run with coverage +tox -- --cov=myst_parser + +# Update regression test fixtures (this will initially produce an error code if the files change) +# but note, these files must pass for all python/sphinx/docutils versions +tox -- --regen-file-failure --force-regen +``` + +### Documentation + +```bash +# Build docs (clean) +tox -e docs-clean + +# Build docs (incremental) +tox -e docs-update + +# Build with a specific builder (e.g., linkcheck) +BUILDER=linkcheck tox -e docs-update +``` + +### Code Quality + +```bash +# Type checking with mypy +tox -e mypy + +# Linting with ruff (auto-fix enabled) +tox -e ruff-check + +# Formatting with ruff +tox -e ruff-fmt + +# Run pre-commit hooks on all files +pre-commit run --all-files +``` + +## Code Style Guidelines + +- **Formatter/Linter**: Ruff (configured in `pyproject.toml`) +- **Type Checking**: Mypy with strict settings (configured in `pyproject.toml`) +- **Pre-commit**: Use pre-commit hooks for consistent code style + +### Best Practices + +- **Type annotations**: Use complete type annotations for all function signatures. Use `TypedDict` for structured dictionaries, dataclasses for configuration. +- **Docstrings**: Use Sphinx-style docstrings (`:param:`, `:return:`, `:raises:`). Types are not required in docstrings as they should be in type hints. +- **Function Signatures**: Use `/` and `*` to enforce positional-only and keyword-only arguments where appropriate +- **Pure functions**: Where possible, write pure functions without side effects. +- **Error handling**: Use `MystWarnings` enum for warning types. Use `create_warning()` for user-facing warnings. +- **Testing**: Write tests for all new functionality. Use `pytest-regressions` for output comparison tests. + +### Docstring Example + +```python +def parse_directive_text( + directive_class: type[Directive], + first_line: str, + content: str, + *, + validate_options: bool = True, +) -> tuple[list[str], dict[str, Any], list[str], int]: + """Parse directive text into its components. + + :param directive_class: The directive class to parse for. + :param first_line: The first line (arguments). + :param content: The directive content. + :param validate_options: Whether to validate options against the directive spec. + :return: Tuple of (arguments, options, body_lines, body_offset). + :raises MarkupError: If the directive text is malformed. + """ + ... +``` + +## Testing Guidelines + +### Test Structure + +- Tests use `pytest` with fixtures from `conftest.py` files +- Sphinx integration tests are in `tests/test_sphinx/` +- Test source directories are in `tests/test_sphinx/sourcedirs/` +- Regression testing uses `pytest-regressions` for output comparison +- Use `pytest-param-files` for parameterized file-based tests + +### Writing Tests + +1. For Sphinx integration tests, create a source directory in `tests/test_sphinx/sourcedirs/` +2. Use `sphinx-pytest` fixtures for Sphinx application testing +3. Use `file_regression` fixture for comparing output against stored fixtures + +### Test Best Practices + +- **Test coverage**: Write tests for all new functionality and bug fixes +- **Isolation**: Each test should be independent and not rely on state from other tests +- **Descriptive names**: Test function names should describe what is being tested +- **Regression testing**: Use `file_regression.check()` for complex output comparisons +- **Parametrization**: Use `@pytest.mark.parametrize` for multiple test scenarios +- **Fixtures**: Define reusable fixtures in `conftest.py` + +### Example Test Pattern + +```python +import pytest + +@pytest.mark.sphinx( + buildername="html", + srcdir="path/to/sourcedir", +) +def test_example(app, status, warning, get_sphinx_app_output): + app.build() + assert "build succeeded" in status.getvalue() + warnings = warning.getvalue().strip() + assert warnings == "" +``` + +## Pull Request Requirements + +When submitting changes: + +1. **Description**: Include a meaningful description or link explaining the change +2. **Tests**: Include test cases for new functionality or bug fixes +3. **Documentation**: Update docs if behavior changes or new features are added +4. **Changelog**: Update `CHANGELOG.md` under the appropriate section +5. **Code Quality**: Ensure `pre-commit run --all-files` passes + +## Architecture Overview + +### Parsing Pipeline + +The MyST parser follows a three-stage pipeline: + +``` +MyST Markdown → markdown-it tokens → docutils AST → Sphinx/HTML output +``` + +1. **Markdown Parsing** (`myst_parser/parsers/mdit.py`): Uses `markdown-it-py` with MyST plugins to parse Markdown into tokens +2. **Token Rendering** (`myst_parser/mdit_to_docutils/`): Converts markdown-it tokens to docutils nodes +3. **Sphinx Integration** (`myst_parser/sphinx_ext/`): Integrates with Sphinx for documentation builds + +### Key Components + +#### Configuration (`myst_parser/config/main.py`) + +The `MdParserConfig` dataclass centralizes all MyST configuration options: + +- Defines all `myst_*` configuration values with types and defaults +- Uses dataclass validators for type checking +- Sphinx config values are auto-registered with `myst_` prefix + +#### Parsers (`myst_parser/parsers/`) + +- `MystParser` (in `sphinx_.py`): The Sphinx parser class that integrates with Sphinx's build system +- `Parser` (in `docutils_.py`): The standalone docutils parser for non-Sphinx use +- `create_md_parser()` (in `mdit.py`): Factory function to create configured markdown-it-py instances + +#### Renderers (`myst_parser/mdit_to_docutils/`) + +- `DocutilsRenderer` (in `base.py`): Base renderer that converts tokens to docutils nodes. Contains render methods for each token type (e.g., `render_heading`, `render_paragraph`). +- `SphinxRenderer` (in `sphinx_.py`): Extends `DocutilsRenderer` with Sphinx-specific functionality (e.g., cross-references, domains). + +#### Sphinx Extension (`myst_parser/sphinx_ext/`) + +- `setup_sphinx()` (in `main.py`): Registers the parser, config values, and transforms with Sphinx +- `MystReferenceResolver` (in `myst_refs.py`): Post-transform that resolves MyST-style references +- Custom directives like `figure-md` (in `directives.py`) + +### Sphinx Integration Flow + +```mermaid +flowchart TB + subgraph init["Initialization"] + setup["setup() in __init__.py"] + setup_sphinx["setup_sphinx()"] + end + + subgraph config["Configuration"] + builder_init["builder-inited"] + create_config["create_myst_config()"] + end + + subgraph parse["Parse Phase"] + source["Source .md file"] + mdit["markdown-it-py parser"] + tokens["Token stream"] + renderer["DocutilsRenderer/SphinxRenderer"] + doctree["Docutils doctree"] + end + + subgraph resolve["Resolution Phase"] + post_transform["MystReferenceResolver"] + resolved["Resolved doctree"] + end + + setup --> setup_sphinx + setup_sphinx --> builder_init + builder_init --> create_config + + source --> mdit --> tokens --> renderer --> doctree + doctree --> post_transform --> resolved + + create_config -.->|"MdParserConfig"| renderer + + style create_config fill:#e1f5fe + style renderer fill:#e1f5fe + style post_transform fill:#e1f5fe +``` + +## Key Files + +- `pyproject.toml` - Project configuration, dependencies, and tool settings +- `myst_parser/__init__.py` - Package entry point with `setup()` for Sphinx +- `myst_parser/config/main.py` - `MdParserConfig` dataclass with all configuration options +- `myst_parser/parsers/sphinx_.py` - `MystParser` class for Sphinx integration +- `myst_parser/mdit_to_docutils/base.py` - `DocutilsRenderer` with token-to-node rendering +- `myst_parser/sphinx_ext/main.py` - `setup_sphinx()` function for Sphinx setup +- `myst_parser/warnings_.py` - `MystWarnings` enum for warning types + +## Debugging + +- Build docs with `-T` flag for full tracebacks: `tox -e docs-clean -- -T ...` +- Use `myst-docutils-html` CLI for standalone parsing without Sphinx +- Check `docs/_build/` for build outputs +- Use `tox -- -v --tb=long` for verbose test output with full tracebacks +- Set `myst_debug_match = True` in Sphinx config to log matched syntax + +## Common Patterns + +### Adding a New Syntax Extension + +1. Create a markdown-it-py plugin or use an existing one from `mdit-py-plugins` +2. Register it in `myst_parser/parsers/mdit.py` +3. Add configuration option in `MdParserConfig` if needed +4. Add render method in `DocutilsRenderer` (e.g., `render_my_syntax`) +5. Document in `docs/syntax/` +6. Add tests in `tests/` + +### Adding a Configuration Option + +1. Add field to `MdParserConfig` in `myst_parser/config/main.py` +2. Add validator if needed in `myst_parser/config/dc_validators.py` +3. Document in `docs/configuration.md` +4. Add tests for the new option + +### Adding a Sphinx Directive + +1. Create directive class in `myst_parser/sphinx_ext/directives.py` +2. Register in `setup_sphinx()` in `myst_parser/sphinx_ext/main.py` +3. Document in appropriate docs section +4. Add tests in `tests/test_sphinx/` + +## Reference Documentation + +- [markdown-it-py Repository](https://github.com/ExecutableBookProject/markdown-it-py) +- [markdown-it-py Documentation](https://markdown-it-py.readthedocs.io/) +- [Docutils Repository](https://github.com/live-clones/docutils) +- [Docutils Documentation](https://docutils.sourceforge.io/) +- [Docutils release log](https://docutils.sourceforge.io/RELEASE-NOTES.html) +- [Sphinx Repository](https://github.com/sphinx-doc/sphinx) +- [Sphinx Extension Development](https://www.sphinx-doc.org/en/master/extdev/index.html) diff --git a/CHANGELOG.md b/CHANGELOG.md index 945f0c5f..07281793 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,43 @@ # Changelog +## 5.0.0 - 2026-01-15 + +This release significantly bumps the supported versions of core dependencies: + +### ‼️ Breaking Changes + +This release updates the minimum supported versions: + +- **Python**: `>=3.11` (dropped Python 3.10, tests up to 3.14) +- **Sphinx**: `>=8,<10` (dropped Sphinx 7, added Sphinx 9) +- **Docutils**: `>=0.20,<0.23` (dropped docutils 0.19, added docutils 0.22) +- **markdown-it-py**: `~=4.0` (upgraded from v3) + +### ⬆️ Dependency Upgrades + +- ⬆️ Upgrade to markdown-it-py v4 by in +- ⬆️ Drop Python 3.10 and Sphinx 7 by in +- ⬆️ Drop docutils 0.19 by in +- ⬆️ Add support for Python 3.14 by in +- ⬆️ Support Sphinx v9 by in +- ⬆️ Allow docutils 0.22 by in + +### 👌 Improvements + +- 👌 Improve generation of meta nodes by in + +### 📚 Documentation + +- 📚 Fix typo in tables.md by in +- 📚 Fix minor typo in `cross-referencing.md` by in + +### 🔧 Internal / Maintenance + +- 🔧 Update pre-commit by in +- 🔧 Add `AGENTS.md` by in + +**Full Changelog**: [v4.0.1...v5.0.0](https://github.com/executablebooks/MyST-Parser/compare/v4.0.1...v5.0.0) + ## 4.0.1 - 2025-02-12 🔧 Minor fix for Sphinx 8.2 compatibility (in ) diff --git a/docs/conf.py b/docs/conf.py index fb3843b9..748bec75 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -54,7 +54,7 @@ suppress_warnings = ["myst.strikethrough"] intersphinx_mapping = { - "python": ("https://docs.python.org/3.10", None), + "python": ("https://docs.python.org/3.11", None), "sphinx": ("https://www.sphinx-doc.org/en/master", None), "markdown_it": ("https://markdown-it-py.readthedocs.io/en/latest", None), } @@ -200,6 +200,8 @@ "https://www.sphinx-doc.org/en/master", "https://markdown-it-py.readthedocs.io/en/latest", ] +# TODO failing +tippy_enable_wikitips = False # -- LaTeX output ------------------------------------------------- diff --git a/docs/syntax/cross-referencing.md b/docs/syntax/cross-referencing.md index e30e57ef..133fbd7d 100644 --- a/docs/syntax/cross-referencing.md +++ b/docs/syntax/cross-referencing.md @@ -376,7 +376,7 @@ Here are some examples: Sphinx offers numerous [roles for referencing](#usage/restructuredtext/roles) specific objects. -These can also within MyST documents, although it is recommended to use the Markdown syntax where possible, which is more portable and native to MyST. +These can also be used within MyST documents, although it is recommended to use the Markdown syntax where possible, which is more portable and native to MyST. :::{myst-example} - {ref}`syntax/referencing`, {ref}`Explicit text ` diff --git a/docs/syntax/tables.md b/docs/syntax/tables.md index 28568021..5effc726 100644 --- a/docs/syntax/tables.md +++ b/docs/syntax/tables.md @@ -54,7 +54,7 @@ The `table` directive can be used to create a table with a caption: The following options are recognized: -:::{admonition} List table options +:::{admonition} Table options :class: hint `align` : "left", "center", or "right" diff --git a/myst_parser/__init__.py b/myst_parser/__init__.py index fc1a023b..782f46d6 100644 --- a/myst_parser/__init__.py +++ b/myst_parser/__init__.py @@ -3,7 +3,7 @@ and [Sphinx](https://github.com/sphinx-doc/sphinx). """ -__version__ = "4.0.1" +__version__ = "5.0.0" def setup(app): diff --git a/myst_parser/_docs.py b/myst_parser/_docs.py index 41212e98..95c8314e 100644 --- a/myst_parser/_docs.py +++ b/myst_parser/_docs.py @@ -211,7 +211,7 @@ def run(self): :Name: `{name}` :Description: {content} :Arguments: {klass.required_arguments} required, {klass.optional_arguments} optional -:Content: {'yes' if klass.has_content else 'no'} +:Content: {"yes" if klass.has_content else "no"} :Options: """ if klass.option_spec: diff --git a/myst_parser/config/main.py b/myst_parser/config/main.py index 2b088b56..275c8e7a 100644 --- a/myst_parser/config/main.py +++ b/myst_parser/config/main.py @@ -64,7 +64,7 @@ def check_url_schemes(inst: "MdParserConfig", field: dc.Field, value: Any) -> No if isinstance(value, list | tuple): if not all(isinstance(v, str) for v in value): raise TypeError(f"'{field.name}' is not a list of strings: {value!r}") - value = {v: None for v in value} + value = dict.fromkeys(value) if not isinstance(value, dict): raise TypeError(f"'{field.name}' is not a dictionary: {value!r}") @@ -522,8 +522,7 @@ def merge_file_level( if "html_meta" in topmatter: warning( MystWarnings.MD_TOPMATTER, - "top-level 'html_meta' key is deprecated, " - "place under 'myst' key instead", + "top-level 'html_meta' key is deprecated, place under 'myst' key instead", ) updates["html_meta"] = topmatter["html_meta"] if "substitutions" in topmatter: diff --git a/myst_parser/inventory.py b/myst_parser/inventory.py index 0782752c..5ece7b6e 100644 --- a/myst_parser/inventory.py +++ b/myst_parser/inventory.py @@ -80,7 +80,7 @@ def to_sphinx(inv: InventoryType) -> SphinxInventoryType: for domain_name, obj_types in inv["objects"].items(): for obj_type, refs in obj_types.items(): for refname, refdata in refs.items(): - objs.setdefault(f"{domain_name}:{obj_type}", {})[refname] = ( + objs.setdefault(f"{domain_name}:{obj_type}", {})[refname] = ( # type: ignore[assignment] inv["name"], inv["version"], refdata["loc"], diff --git a/myst_parser/mdit_to_docutils/base.py b/myst_parser/mdit_to_docutils/base.py index 3778dd31..85d64be3 100644 --- a/myst_parser/mdit_to_docutils/base.py +++ b/myst_parser/mdit_to_docutils/base.py @@ -28,7 +28,6 @@ from docutils.parsers.rst.directives.misc import Include from docutils.parsers.rst.languages import get_language as get_language_rst from docutils.statemachine import StringList -from docutils.transforms.components import Filter from docutils.utils import Reporter, SystemMessage, new_document from docutils.utils.code_analyzer import Lexer, LexerError, NumberLines from markdown_it import MarkdownIt @@ -976,8 +975,7 @@ def render_link_path(self, token: SyntaxTreeNode) -> None: def render_link_project(self, token: SyntaxTreeNode) -> None: """Render a link token like ``.""" destination = cast(str, token.attrGet("href") or "") - if destination.startswith("project:"): - destination = destination[8:] + destination = destination.removeprefix("project:") if destination.startswith("#"): return self.render_link_anchor(token, destination) self.create_warning( @@ -1796,13 +1794,13 @@ def run_directive( ) return [error_msg] - assert isinstance( - result, list - ), f'Directive "{name}" must return a list of nodes.' + assert isinstance(result, list), ( + f'Directive "{name}" must return a list of nodes.' + ) for i in range(len(result)): - assert isinstance( - result[i], nodes.Node - ), f'Directive "{name}" returned non-Node object (index {i}): {result[i]}' + assert isinstance(result[i], nodes.Node), ( + f'Directive "{name}" returned non-Node object (index {i}): {result[i]}' + ) return result def render_substitution_inline(self, token: SyntaxTreeNode) -> None: @@ -1884,7 +1882,7 @@ def render_substitution(self, token: SyntaxTreeNode, inline: bool) -> None: def html_meta_to_nodes( data: dict[str, Any], document: nodes.document, line: int, reporter: Reporter -) -> list[nodes.pending | nodes.system_message]: +) -> list[nodes.meta | nodes.system_message]: """Replicate the `meta` directive, by converting a dictionary to a list of pending meta nodes @@ -1918,14 +1916,8 @@ def html_meta_to_nodes( except ValueError as error: msg = reporter.error(f'Error parsing meta tag attribute "{key}": {error}.') output.append(msg) - continue - - pending = nodes.pending( - Filter, - {"component": "writer", "format": "html", "nodes": [meta_node]}, - ) - document.note_pending(pending) - output.append(pending) + else: + output.append(meta_node) return output diff --git a/myst_parser/mdit_to_docutils/sphinx_.py b/myst_parser/mdit_to_docutils/sphinx_.py index b9b29225..1569131f 100644 --- a/myst_parser/mdit_to_docutils/sphinx_.py +++ b/myst_parser/mdit_to_docutils/sphinx_.py @@ -72,8 +72,7 @@ def _handle_relative_docs(self, destination: str) -> str: def render_link_project(self, token: SyntaxTreeNode) -> None: destination = cast(str, token.attrGet("href") or "") - if destination.startswith("project:"): - destination = destination[8:] + destination = destination.removeprefix("project:") if destination.startswith("#"): return self.render_link_anchor(token, destination) @@ -108,8 +107,7 @@ def render_link_project(self, token: SyntaxTreeNode) -> None: def render_link_path(self, token: SyntaxTreeNode) -> None: destination = self.md.normalizeLinkText(cast(str, token.attrGet("href") or "")) - if destination.startswith("path:"): - destination = destination[5:] + destination = destination.removeprefix("path:") destination = self._handle_relative_docs(destination) explicit = (token.info != "auto") and (len(token.children or []) > 0) wrap_node = addnodes.download_reference( diff --git a/myst_parser/mocking.py b/myst_parser/mocking.py index 61a2b172..f809c6d7 100644 --- a/myst_parser/mocking.py +++ b/myst_parser/mocking.py @@ -454,15 +454,20 @@ def run(self) -> list[nodes.Element]: literal_block.line = 1 # TODO don;t think this should be 1? self.add_name(literal_block) if "number-lines" in self.options: - try: - startline = int(self.options["number-lines"] or 1) - except ValueError as err: - raise DirectiveError( - 3, ":number-lines: with non-integer start value" - ) from err + # note starting in docutils 0.22 this option is now an integer instead of a string, see: https://github.com/live-clones/docutils/commit/f39ac1413e56a330c8fea6e0d080fed0ff2b8483 + if self.options["number-lines"] is None: + startline = 1 + elif isinstance(self.options["number-lines"], int): + startline = self.options["number-lines"] + else: + try: + startline = int(self.options["number-lines"] or 1) + except ValueError as err: + raise DirectiveError( + 3, ":number-lines: with non-integer start value" + ) from err endline = startline + len(file_content.splitlines()) - if file_content.endswith("\n"): - file_content = file_content[:-1] + file_content = file_content.removesuffix("\n") tokens = NumberLines([([], file_content)], startline, endline) for classes, value in tokens: if classes: diff --git a/myst_parser/parsers/docutils_.py b/myst_parser/parsers/docutils_.py index e17de44b..2174175c 100644 --- a/myst_parser/parsers/docutils_.py +++ b/myst_parser/parsers/docutils_.py @@ -116,7 +116,7 @@ def _validate_url_schemes( except Exception as err: raise ValueError("Invalid YAML string") from err if isinstance(output, str): - output = {k: None for k in output.split(",")} + output = dict.fromkeys(output.split(",")) if not isinstance(output, dict): raise ValueError("Expecting a comma-delimited str or YAML dictionary") return output @@ -278,7 +278,7 @@ def parse(self, inputstring: str, document: nodes.document) -> None: for i, line in enumerate(inputstring.split("\n")): if len(line) > document.settings.line_length_limit: error = document.reporter.error( - f"Line {i+1} exceeds the line-length-limit:" + f"Line {i + 1} exceeds the line-length-limit:" f" {document.settings.line_length_limit}." ) document.append(error) @@ -479,7 +479,7 @@ def visit_rubric_html(self, node): So here we override the visit/depart methods to output the correct element """ if "level" in node: - self.body.append(self.starttag(node, f'h{node["level"]}', "", CLASS="rubric")) + self.body.append(self.starttag(node, f"h{node['level']}", "", CLASS="rubric")) else: self.body.append(self.starttag(node, "p", "", CLASS="rubric")) @@ -490,7 +490,7 @@ def depart_rubric_html(self, node): See explanation in `visit_rubric_html` """ if "level" in node: - self.body.append(f'\n') + self.body.append(f"\n") else: self.body.append("

\n") diff --git a/myst_parser/sphinx_ext/main.py b/myst_parser/sphinx_ext/main.py index eda129ac..3788a5a2 100644 --- a/myst_parser/sphinx_ext/main.py +++ b/myst_parser/sphinx_ext/main.py @@ -2,7 +2,6 @@ from typing import Any -import sphinx from docutils import nodes from sphinx.application import Sphinx from sphinx.transforms import ( @@ -12,9 +11,7 @@ from myst_parser.mdit_to_docutils.transforms import UnreferencedFootnotesDetector from myst_parser.parsers.docutils_ import ( depart_container_html, - depart_rubric_html, visit_container_html, - visit_rubric_html, ) from myst_parser.warnings_ import MystWarnings @@ -51,13 +48,6 @@ def setup_sphinx(app: Sphinx, load_parser: bool = False) -> None: app.add_post_transform(MystReferenceResolver) - # override only the html writer visit methods for rubric, to use the "level" attribute - # this allows for nested headers to be correctly rendered - if sphinx.version_info < (7, 4): - # This is now added in sphinx: https://github.com/sphinx-doc/sphinx/pull/12506 - app.add_node( - nodes.rubric, override=True, html=(visit_rubric_html, depart_rubric_html) - ) # override only the html writer visit methods for container, # to remove the "container" class for divs # this avoids CSS clashes with the bootstrap theme @@ -70,7 +60,7 @@ def setup_sphinx(app: Sphinx, load_parser: bool = False) -> None: for name, default, field in MdParserConfig().as_triple(): if "sphinx" not in field.metadata.get("omit", []): # TODO add types? - app.add_config_value(f"myst_{name}", default, "env", types=Any) # type: ignore[arg-type] + app.add_config_value(f"myst_{name}", default, "env", types=Any) app.connect("builder-inited", create_myst_config) app.connect("builder-inited", override_mathjax) diff --git a/pyproject.toml b/pyproject.toml index e97dff7f..1f9440f9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -15,10 +15,10 @@ classifiers = [ "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", - "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", "Programming Language :: Python :: Implementation :: CPython", "Programming Language :: Python :: Implementation :: PyPy", "Topic :: Software Development :: Libraries :: Python Modules", @@ -32,14 +32,14 @@ keywords = [ "docutils", "sphinx", ] -requires-python = ">=3.10" +requires-python = ">=3.11" dependencies = [ - "docutils>=0.19,<0.22", + "docutils>=0.20,<0.23", "jinja2", # required for substitutions, but let sphinx choose version - "markdown-it-py~=3.0", - "mdit-py-plugins~=0.4,>=0.4.1", + "markdown-it-py~=4.0", + "mdit-py-plugins~=0.5", "pyyaml", - "sphinx>=7,<9", + "sphinx>=8,<10", ] [project.urls] @@ -52,15 +52,15 @@ code_style = ["pre-commit~=4.0"] linkify = ["linkify-it-py~=2.0"] # Note: This is only required for internal use rtd = [ - "sphinx>=7", + "sphinx>=8", "ipython", "sphinx-book-theme~=1.1", "sphinx-design", "sphinx-copybutton", - "sphinxext-rediraffe~=0.2.7", + "sphinxext-rediraffe~=0.3.0", # TODO this can uncommented once https://github.com/mgaitan/sphinxcontrib-mermaid/issues/109 is fixed # "sphinxcontrib.mermaid~=0.7.1", - "sphinxext-opengraph~=0.9.0", + "sphinxext-opengraph~=0.13.0", "sphinx-pyscript", "sphinx-tippy>=0.4.3", "sphinx-autodoc2~=0.5.0", @@ -70,19 +70,29 @@ testing = [ "beautifulsoup4", "coverage[toml]", "defusedxml", # required by sphinx 7.3 testing utils - "pytest>=8,<9", + "pytest>=9,<10", "pytest-cov", "pytest-regressions", "pytest-param-files~=0.6.0", - "sphinx-pytest", - "pygments<2.19", # TODO fix test regression with 2.19" + "sphinx-pytest~=0.3.0", + "pygments<2.20", # TODO fix test regression with 2.19" ] testing-docutils = [ "pygments", - "pytest>=8,<9", + "pytest>=9,<10", "pytest-param-files~=0.6.0", ] +[dependency-groups] +mypy = [ + "mypy==1.19.1", + "types-urllib3", + "sphinx~=8.2", + "markdown-it-py~=4.0", + "mdit-py-plugins~=0.5.0", +] +ruff = ["ruff==0.14.11"] + [project.scripts] myst-anchors = "myst_parser.cli:print_anchors" myst-inv = "myst_parser.inventory:inventory_cli" @@ -136,6 +146,7 @@ disallow_any_generics = false [tool.pytest.ini_options] filterwarnings = [ "ignore:.*The default for the setting.*:FutureWarning", + "ignore:.*:PendingDeprecationWarning", ] [tool.coverage.run] diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 00000000..7952e9f2 --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,54 @@ +"""Shared pytest configuration for all tests.""" + +import re + +from docutils import __version_info__ as docutils_version_info + +DOCUTILS_0_22_PLUS = docutils_version_info >= (0, 22) + + +def normalize_doctree_xml(text: str) -> str: + """Normalize docutils XML output for cross-version compatibility. + + In docutils 0.22+, boolean attributes are serialized as "1"/"0" + instead of "True"/"False". This function normalizes to the old format + for consistent test fixtures. + """ + if DOCUTILS_0_22_PLUS: + # Normalize new format (1/0) to old format (1/0) + # Only replace when it's clearly a boolean attribute value + # Pattern: attribute="1" or attribute="0" + attrs = [ + "force", + "glob", + "hidden", + "id_link", + "includehidden", + "inline", + "internal", + "is_div", + "linenos", + "multi_line_parameter_list", + "multi_line_trailing_comma", + "no-contents-entry", + "no-index", + "no-index-entry", + "no-typesetting", + "no-wrap", + "nocontentsentry", + "noindex", + "noindexentry", + "nowrap", + "refexplicit", + "refspecific", + "refwarn", + "sorted", + "titlesonly", + "toctree", + "translatable", + ] + text = re.sub(rf' ({"|".join(attrs)})="1"', r' \1="True"', text) + text = re.sub(rf' ({"|".join(attrs)})="0"', r' \1="False"', text) + # numbered is changed in math_block, but not in toctree, so we have to be more precise + text = re.sub(r' numbered="1" xml:space', r' numbered="True" xml:space', text) + return text diff --git a/tests/test_commonmark/commonmark.json b/tests/test_commonmark/commonmark.json index 222fee42..3c27e7ad 100644 --- a/tests/test_commonmark/commonmark.json +++ b/tests/test_commonmark/commonmark.json @@ -4969,7 +4969,7 @@ }, { "markdown": "foo \n", - "html": "

foo <!-- not a comment -- two hyphens -->

\n", + "html": "

foo

\n", "example": 622, "start_line": 9087, "end_line": 9091, @@ -4977,7 +4977,7 @@ }, { "markdown": "foo foo -->\n\nfoo \n", - "html": "

foo <!--> foo -->

\n

foo <!-- foo--->

\n", + "html": "

foo foo -->

\n

foo <!-- foo--->

\n", "example": 623, "start_line": 9096, "end_line": 9103, diff --git a/tests/test_html/test_html_to_nodes.py b/tests/test_html/test_html_to_nodes.py index 207a6274..08423a79 100644 --- a/tests/test_html/test_html_to_nodes.py +++ b/tests/test_html/test_html_to_nodes.py @@ -6,6 +6,7 @@ from myst_parser.config.main import MdParserConfig from myst_parser.mdit_to_docutils.html_to_nodes import html_to_nodes +from tests.conftest import normalize_doctree_xml FIXTURE_PATH = Path(__file__).parent @@ -32,4 +33,4 @@ def _run_directive(name: str, first_line: str, content: str, position: int): def test_html_to_nodes(file_params, mock_renderer): output = nodes.container() output += html_to_nodes(file_params.content, line_number=0, renderer=mock_renderer) - file_params.assert_expected(output.pformat(), rstrip=True) + file_params.assert_expected(normalize_doctree_xml(output.pformat()), rstrip=True) diff --git a/tests/test_renderers/fixtures/docutil_link_resolution.md b/tests/test_renderers/fixtures/docutil_link_resolution.md index e686e17c..3942a915 100644 --- a/tests/test_renderers/fixtures/docutil_link_resolution.md +++ b/tests/test_renderers/fixtures/docutil_link_resolution.md @@ -128,14 +128,15 @@ Test Other - - - Duplicate implicit target name: "test". Other + + +/index.md:3: (INFO/1) Target name overrides implicit target name "test". +/index.md:3: (INFO/1) Hyperlink target "test-1" is not referenced. . [id-with-spaces] diff --git a/tests/test_renderers/fixtures/docutil_syntax_elements.md b/tests/test_renderers/fixtures/docutil_syntax_elements.md index 67668bf3..8c323b52 100644 --- a/tests/test_renderers/fixtures/docutil_syntax_elements.md +++ b/tests/test_renderers/fixtures/docutil_syntax_elements.md @@ -672,38 +672,10 @@ myst: --- . - - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - - - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - - - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - - - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - + + + + . Full Test: diff --git a/tests/test_renderers/fixtures/myst-config.txt b/tests/test_renderers/fixtures/myst-config.txt index 765b0108..1f009a66 100644 --- a/tests/test_renderers/fixtures/myst-config.txt +++ b/tests/test_renderers/fixtures/myst-config.txt @@ -263,6 +263,12 @@ a a +
+ + Docutils System Messages + <system_message level="2" source="<string>" type="WARNING"> + <paragraph> + The `attrs_image` extension is deprecated, please use `attrs_inline` instead. [myst.deprecated] <string>:: (WARNING/2) The `attrs_image` extension is deprecated, please use `attrs_inline` instead. [myst.deprecated] . diff --git a/tests/test_renderers/fixtures/sphinx_directives.md b/tests/test_renderers/fixtures/sphinx_directives.md index bb2ba2df..99370f05 100644 --- a/tests/test_renderers/fixtures/sphinx_directives.md +++ b/tests/test_renderers/fixtures/sphinx_directives.md @@ -21,7 +21,7 @@ object (`sphinx.directives.ObjectDescription`): . <document source="<src>/index.md"> <index entries=""> - <desc classes="object" desctype="object" domain="" nocontentsentry="False" noindex="False" noindexentry="False" objtype="object"> + <desc classes="object" desctype="object" domain="" no-contents-entry="False" no-index="False" no-index-entry="False" no-typesetting="False" nocontentsentry="False" noindex="False" noindexentry="False" objtype="object"> <desc_signature _toc_name="" _toc_parts="()" classes="sig sig-object"> <desc_name classes="sig-name descname" xml:space="preserve"> something @@ -323,7 +323,7 @@ math (`sphinx.directives.patches.MathDirective`): ``` . <document source="<src>/index.md"> - <math_block docname="index" label="True" nowrap="False" number="True" xml:space="preserve"> + <math_block docname="index" label="True" no-wrap="False" nowrap="False" number="True" xml:space="preserve"> . deprecated (`sphinx.domains.changeset.VersionChange`): @@ -347,7 +347,7 @@ versionadded (`sphinx.domains.changeset.VersionChange`): <versionmodified type="versionadded" version="0.2"> <paragraph translatable="False"> <inline classes="versionmodified added"> - New in version 0.2. + Added in version 0.2. . versionchanged (`sphinx.domains.changeset.VersionChange`): @@ -372,7 +372,7 @@ term 2 : B ``` . <document source="<src>/index.md"> - <glossary> + <glossary sorted="False"> <definition_list classes="glossary"> <definition_list_item> <term ids="term-term-1"> @@ -386,7 +386,7 @@ term 2 : B Definition of both terms. . -SPHINX4-SKIP productionlist (`sphinx.domains.std.ProductionList`): +SKIP productionlist (`sphinx.domains.std.ProductionList`): . ```{productionlist} try_stmt: try1_stmt | try2_stmt ``` @@ -404,7 +404,7 @@ cmdoption (`sphinx.domains.std.Cmdoption`): . <document source="<src>/index.md"> <index entries="('pair',\ 'command\ line\ option;\ a',\ 'cmdoption-arg-a',\ '',\ None)"> - <desc classes="std cmdoption" desctype="cmdoption" domain="std" nocontentsentry="False" noindex="False" noindexentry="False" objtype="cmdoption"> + <desc classes="std cmdoption" desctype="cmdoption" domain="std" no-contents-entry="False" no-index="False" no-index-entry="False" no-typesetting="False" nocontentsentry="False" noindex="False" noindexentry="False" objtype="cmdoption"> <desc_signature _toc_name="" _toc_parts="()" allnames="a" classes="sig sig-object" ids="cmdoption-arg-a"> <desc_name classes="sig-name descname" xml:space="preserve"> a @@ -419,14 +419,14 @@ rst:directive (`sphinx.domains.rst.ReSTDirective`): . <document source="<src>/index.md"> <index entries="('single',\ 'a\ (directive)',\ 'directive-a',\ '',\ None)"> - <desc classes="rst directive" desctype="directive" domain="rst" nocontentsentry="False" noindex="False" noindexentry="False" objtype="directive"> + <desc classes="rst directive" desctype="directive" domain="rst" no-contents-entry="False" no-index="False" no-index-entry="False" no-typesetting="False" nocontentsentry="False" noindex="False" noindexentry="False" objtype="directive"> <desc_signature _toc_name=".. a::" _toc_parts="('a',)" classes="sig sig-object" fullname="a" ids="directive-a"> <desc_name classes="sig-name descname" xml:space="preserve"> .. a:: <desc_content> . -SPHINX4-SKIP rst:directive:option (`sphinx.domains.rst.ReSTDirectiveOption`): +SKIP rst:directive:option (`sphinx.domains.rst.ReSTDirectiveOption`): . ```{rst:directive:option} a ``` diff --git a/tests/test_renderers/fixtures/sphinx_roles.md b/tests/test_renderers/fixtures/sphinx_roles.md index 37683dbe..d74b14f4 100644 --- a/tests/test_renderers/fixtures/sphinx_roles.md +++ b/tests/test_renderers/fixtures/sphinx_roles.md @@ -228,7 +228,7 @@ js:class (`sphinx.domains.javascript.JSConstructor`): <paragraph> <pending_xref js:module="True" js:object="True" refdoc="index" refdomain="js" refexplicit="False" reftarget="a" reftype="class" refwarn="False"> <literal classes="xref js js-class"> - a() + a . js:data (`sphinx.domains.javascript.JSObject`): diff --git a/tests/test_renderers/fixtures/sphinx_syntax_elements.md b/tests/test_renderers/fixtures/sphinx_syntax_elements.md index 1f6e1fcb..6b90d3ad 100644 --- a/tests/test_renderers/fixtures/sphinx_syntax_elements.md +++ b/tests/test_renderers/fixtures/sphinx_syntax_elements.md @@ -169,7 +169,7 @@ Image empty: . <document source="<src>/index.md"> <paragraph> - <image alt="" uri=""> + <image alt="" candidates="{'*': '.'}" original_uri="" uri="."> . Image with alt and title: @@ -178,7 +178,7 @@ Image with alt and title: . <document source="<src>/index.md"> <paragraph> - <image alt="alt" title="title" uri="src"> + <image alt="alt" candidates="{'*': 'src'}" title="title" uri="src"> . Image with escapable html: @@ -187,7 +187,7 @@ Image with escapable html: . <document source="<src>/index.md"> <paragraph> - <image alt="alt" uri="http://www.google%3C%3E.com"> + <image alt="alt" candidates="{'?': 'http://www.google%3C%3E.com'}" uri="http://www.google%3C%3E.com"> . Block Quote: @@ -674,38 +674,10 @@ myst: --- . <document source="<src>/index.md"> - <pending> - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - <meta content="Sphinx, documentation, builder" name="keywords"> - <pending> - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - <meta content="An amusing story" lang="en" name="description"> - <pending> - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - <meta content="Un histoire amusant" lang="fr" name="description"> - <pending> - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"> + <meta content="Sphinx, documentation, builder" name="keywords"> + <meta content="An amusing story" lang="en" name="description"> + <meta content="Un histoire amusant" lang="fr" name="description"> + <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"> . Full Test: diff --git a/tests/test_renderers/test_error_reporting.py b/tests/test_renderers/test_error_reporting.py index 196da30d..17d68bcf 100644 --- a/tests/test_renderers/test_error_reporting.py +++ b/tests/test_renderers/test_error_reporting.py @@ -20,4 +20,9 @@ def test_basic(file_params): parser=Parser(), settings_overrides={"warning_stream": report_stream}, ) - file_params.assert_expected(report_stream.getvalue(), rstrip=True) + text = report_stream.getvalue() + # changed in docutils 0.23 + text = text.replace( + "corresponding footnote available", "corresponding footnotes available" + ) + file_params.assert_expected(text, rstrip=True) diff --git a/tests/test_renderers/test_fixtures_docutils.py b/tests/test_renderers/test_fixtures_docutils.py index 86c7d095..c46e51c7 100644 --- a/tests/test_renderers/test_fixtures_docutils.py +++ b/tests/test_renderers/test_fixtures_docutils.py @@ -11,6 +11,8 @@ from typing import Any import pytest +from conftest import normalize_doctree_xml +from docutils import __version_info__ as docutils_version from docutils.core import Publisher, publish_doctree from pytest_param_files import ParamTestData @@ -37,7 +39,9 @@ def _apply_transforms(self): ) # in docutils 0.18 footnote ids have changed - outcome = doctree.pformat().replace('"footnote-reference-1"', '"id1"') + outcome = normalize_doctree_xml(doctree.pformat()).replace( + '"footnote-reference-1"', '"id1"' + ) outcome = outcome.replace(' language=""', "") file_params.assert_expected(outcome, rstrip_lines=True) @@ -48,13 +52,18 @@ def test_link_resolution(file_params: ParamTestData): settings = settings_from_cmdline(file_params.description) report_stream = StringIO() settings["warning_stream"] = report_stream + if file_params.title == "explicit>implicit": + if docutils_version < (0, 22): + # reporting changed in docutils 0.22 + pytest.skip("different in docutils>=0.22") + settings["report_level"] = 0 doctree = publish_doctree( file_params.content, source_path="<src>/index.md", parser=Parser(), settings_overrides=settings, ) - outcome = doctree.pformat() + outcome = normalize_doctree_xml(doctree.pformat()) if report_stream.getvalue().strip(): outcome += "\n\n" + report_stream.getvalue().strip() file_params.assert_expected(outcome, rstrip_lines=True) @@ -75,7 +84,9 @@ def _apply_transforms(self): parser=Parser(), ) - file_params.assert_expected(doctree.pformat(), rstrip_lines=True) + file_params.assert_expected( + normalize_doctree_xml(doctree.pformat()), rstrip_lines=True + ) @pytest.mark.param_file(FIXTURE_PATH / "docutil_directives.md") @@ -95,7 +106,9 @@ def _apply_transforms(self): parser=Parser(), ) - file_params.assert_expected(doctree.pformat(), rstrip_lines=True) + file_params.assert_expected( + normalize_doctree_xml(doctree.pformat()), rstrip_lines=True + ) @pytest.mark.param_file(FIXTURE_PATH / "docutil_syntax_extensions.txt") @@ -109,7 +122,9 @@ def test_syntax_extensions(file_params: ParamTestData): parser=Parser(), settings_overrides=settings, ) - file_params.assert_expected(doctree.pformat(), rstrip_lines=True) + file_params.assert_expected( + normalize_doctree_xml(doctree.pformat()), rstrip_lines=True + ) def settings_from_cmdline(cmdline: str | None) -> dict[str, Any]: diff --git a/tests/test_renderers/test_fixtures_sphinx.py b/tests/test_renderers/test_fixtures_sphinx.py index f763251a..c061febc 100644 --- a/tests/test_renderers/test_fixtures_sphinx.py +++ b/tests/test_renderers/test_fixtures_sphinx.py @@ -13,9 +13,11 @@ import pytest from docutils.core import Publisher from pytest_param_files import ParamTestData +from sphinx.transforms import SphinxTransformer from sphinx_pytest.plugin import CreateDoctree from myst_parser.mdit_to_docutils.sphinx_ import SphinxRenderer +from tests.conftest import normalize_doctree_xml FIXTURE_PATH = Path(__file__).parent.joinpath("fixtures") @@ -31,13 +33,21 @@ def _apply_transforms(self): if "[APPLY TRANSFORMS]" not in file_params.title: monkeypatch.setattr(Publisher, "apply_transforms", _apply_transforms) + # in sphinx >= 9.0.0 SphinxTransformer is used + monkeypatch.setattr(SphinxTransformer, "apply_transforms", _apply_transforms) result = sphinx_doctree(file_params.content, "index.md") - pformat = result.pformat("index") - # changed in docutils 0.20.1 - pformat = pformat.replace( - '<literal classes="code" language="">', '<literal classes="code">' - ) + pformat = normalize_doctree_xml(result.pformat("index")) + replacements = { + # changed in docutils 0.20.1 + '<literal classes="code" language="">': '<literal classes="code">', + # changed in sphinx 9 + '<image alt="" uri="">': '<image alt="" candidates="{\'*\': \'.\'}" original_uri="" uri=".">', + '<image alt="alt" title="title" uri="src">': '<image alt="alt" candidates="{\'*\': \'src\'}" title="title" uri="src">', + '<image alt="alt" uri="http://www.google%3C%3E.com">': '<image alt="alt" candidates="{\'?\': \'http://www.google%3C%3E.com\'}" uri="http://www.google%3C%3E.com">', + } + for old, new in replacements.items(): + pformat = pformat.replace(old, new) file_params.assert_expected(pformat, rstrip_lines=True) @@ -49,7 +59,7 @@ def test_link_resolution(file_params: ParamTestData, sphinx_doctree: CreateDoctr sphinx_doctree.srcdir.joinpath("test.txt").touch() sphinx_doctree.srcdir.joinpath("other.rst").write_text(":orphan:\n\nTest\n====") result = sphinx_doctree(file_params.content, "index.md") - outcome = result.pformat("index") + outcome = normalize_doctree_xml(result.pformat("index")) if result.warnings.strip(): outcome += "\n\n" + result.warnings.strip() file_params.assert_expected(outcome, rstrip_lines=True) @@ -71,7 +81,9 @@ def settings_from_json(string: str | None): def test_tables(file_params: ParamTestData, sphinx_doctree_no_tr: CreateDoctree): sphinx_doctree_no_tr.set_conf({"extensions": ["myst_parser"]}) result = sphinx_doctree_no_tr(file_params.content, "index.md") - file_params.assert_expected(result.pformat("index"), rstrip_lines=True) + file_params.assert_expected( + normalize_doctree_xml(result.pformat("index")), rstrip_lines=True + ) @pytest.mark.param_file(FIXTURE_PATH / "directive_options.md") @@ -80,7 +92,9 @@ def test_directive_options( ): sphinx_doctree_no_tr.set_conf({"extensions": ["myst_parser"]}) result = sphinx_doctree_no_tr(file_params.content, "index.md") - file_params.assert_expected(result.pformat("index"), rstrip_lines=True) + file_params.assert_expected( + normalize_doctree_xml(result.pformat("index")), rstrip_lines=True + ) @pytest.mark.param_file(FIXTURE_PATH / "sphinx_directives.md") @@ -89,40 +103,16 @@ def test_sphinx_directives( ): # TODO fix skipped directives # TODO test domain directives - if file_params.title.startswith("SKIP") or file_params.title.startswith( - "SPHINX4-SKIP" - ): + if file_params.title.startswith("SKIP"): pytest.skip(file_params.title) sphinx_doctree_no_tr.set_conf({"extensions": ["myst_parser"]}) - pformat = sphinx_doctree_no_tr(file_params.content, "index.md").pformat("index") - # see https://github.com/sphinx-doc/sphinx/issues/9827 - pformat = pformat.replace('<glossary sorted="False">', "<glossary>") + pformat = normalize_doctree_xml( + sphinx_doctree_no_tr(file_params.content, "index.md").pformat("index") + ) # see https://github.com/executablebooks/MyST-Parser/issues/522 if sys.maxsize == 2147483647: pformat = pformat.replace('"2147483647"', '"9223372036854775807"') - # changed in sphinx 7.1 (but fixed in 7.2) - pformat = pformat.replace( - 'classes="sig sig-object sig sig-object"', 'classes="sig sig-object"' - ) - pformat = pformat.replace( - 'classes="sig-name descname sig-name descname"', 'classes="sig-name descname"' - ) - pformat = pformat.replace( - 'classes="sig-prename descclassname sig-prename descclassname"', - 'classes="sig-prename descclassname"', - ) - # changed in sphinx 7.2 (#11533) - pformat = pformat.replace( - ( - 'no-contents-entry="False" no-index="False" ' - 'no-index-entry="False" no-typesetting="False" ' - ), - "", - ) - # changed in sphinx 7.3 - pformat = pformat.replace("Added in version 0.2", "New in version 0.2") - file_params.assert_expected(pformat, rstrip_lines=True) @@ -132,7 +122,9 @@ def test_sphinx_roles(file_params: ParamTestData, sphinx_doctree_no_tr: CreateDo pytest.skip(file_params.title) sphinx_doctree_no_tr.set_conf({"extensions": ["myst_parser"]}) - pformat = sphinx_doctree_no_tr(file_params.content, "index.md").pformat("index") + pformat = normalize_doctree_xml( + sphinx_doctree_no_tr(file_params.content, "index.md").pformat("index") + ) # sphinx 3 adds a parent key pformat = re.sub('cpp:parent_key="[^"]*"', 'cpp:parent_key=""', pformat) # sphinx >= 4.5.0 adds a trailing slash to PEP URLs, @@ -141,6 +133,9 @@ def test_sphinx_roles(file_params: ParamTestData, sphinx_doctree_no_tr: CreateDo ' refuri="http://www.python.org/dev/peps/pep-0001">', ' refuri="http://www.python.org/dev/peps/pep-0001/">', ) + if file_params.title == "js:class (`sphinx.domains.javascript.JSConstructor`):": + # sphinx 9 change + pformat = pformat.replace("a()", "a") file_params.assert_expected(pformat, rstrip_lines=True) @@ -150,7 +145,9 @@ def test_dollarmath(file_params: ParamTestData, sphinx_doctree_no_tr: CreateDoct {"extensions": ["myst_parser"], "myst_enable_extensions": ["dollarmath"]} ) result = sphinx_doctree_no_tr(file_params.content, "index.md") - file_params.assert_expected(result.pformat("index"), rstrip_lines=True) + file_params.assert_expected( + normalize_doctree_xml(result.pformat("index")), rstrip_lines=True + ) @pytest.mark.param_file(FIXTURE_PATH / "amsmath.md") @@ -162,7 +159,9 @@ def test_amsmath( {"extensions": ["myst_parser"], "myst_enable_extensions": ["amsmath"]} ) result = sphinx_doctree_no_tr(file_params.content, "index.md") - file_params.assert_expected(result.pformat("index"), rstrip_lines=True) + file_params.assert_expected( + normalize_doctree_xml(result.pformat("index")), rstrip_lines=True + ) @pytest.mark.param_file(FIXTURE_PATH / "containers.md") @@ -174,7 +173,9 @@ def test_containers( {"extensions": ["myst_parser"], "myst_enable_extensions": ["colon_fence"]} ) result = sphinx_doctree_no_tr(file_params.content, "index.md") - file_params.assert_expected(result.pformat("index"), rstrip_lines=True) + file_params.assert_expected( + normalize_doctree_xml(result.pformat("index")), rstrip_lines=True + ) @pytest.mark.param_file(FIXTURE_PATH / "eval_rst.md") @@ -183,7 +184,9 @@ def test_evalrst_elements( ): sphinx_doctree_no_tr.set_conf({"extensions": ["myst_parser"]}) result = sphinx_doctree_no_tr(file_params.content, "index.md") - file_params.assert_expected(result.pformat("index"), rstrip_lines=True) + file_params.assert_expected( + normalize_doctree_xml(result.pformat("index")), rstrip_lines=True + ) @pytest.mark.param_file(FIXTURE_PATH / "definition_lists.md") @@ -194,7 +197,9 @@ def test_definition_lists( {"extensions": ["myst_parser"], "myst_enable_extensions": ["deflist"]} ) result = sphinx_doctree_no_tr(file_params.content, "index.md") - file_params.assert_expected(result.pformat("index"), rstrip_lines=True) + file_params.assert_expected( + normalize_doctree_xml(result.pformat("index")), rstrip_lines=True + ) @pytest.mark.param_file(FIXTURE_PATH / "attributes.md") @@ -206,4 +211,6 @@ def test_attributes(file_params: ParamTestData, sphinx_doctree_no_tr: CreateDoct } ) result = sphinx_doctree_no_tr(file_params.content, "index.md") - file_params.assert_expected(result.pformat("index"), rstrip_lines=True) + file_params.assert_expected( + normalize_doctree_xml(result.pformat("index")), rstrip_lines=True + ) diff --git a/tests/test_renderers/test_include_directive.py b/tests/test_renderers/test_include_directive.py index 51d421e6..e7065747 100644 --- a/tests/test_renderers/test_include_directive.py +++ b/tests/test_renderers/test_include_directive.py @@ -3,6 +3,7 @@ from pathlib import Path import pytest +from conftest import normalize_doctree_xml from docutils.core import publish_doctree from myst_parser.parsers.docutils_ import Parser @@ -24,7 +25,11 @@ def test_render(file_params, tmp_path, monkeypatch): ) doctree["source"] = "tmpdir/test.md" - output = doctree.pformat().replace(str(tmp_path) + os.sep, "tmpdir/").rstrip() + output = ( + normalize_doctree_xml(doctree.pformat()) + .replace(str(tmp_path) + os.sep, "tmpdir/") + .rstrip() + ) file_params.assert_expected(output, rstrip=True) diff --git a/tests/test_renderers/test_myst_config.py b/tests/test_renderers/test_myst_config.py index 8ee5f8db..9a276cce 100644 --- a/tests/test_renderers/test_myst_config.py +++ b/tests/test_renderers/test_myst_config.py @@ -5,6 +5,8 @@ from pathlib import Path import pytest +from conftest import normalize_doctree_xml +from docutils import __version_info__ as docutils_version from docutils.core import Publisher, publish_string from pytest_param_files import ParamTestData @@ -17,6 +19,9 @@ @pytest.mark.param_file(FIXTURE_PATH / "myst-config.txt") def test_cmdline(file_params: ParamTestData): """The description is parsed as a docutils commandline""" + if file_params.title == "attrs_image" and docutils_version < (0, 22): + # loose system messages are also output to ast in 0.22 https://github.com/live-clones/docutils/commit/dc4e16315b4fbe391417a6f7aad215b9389a9c74 + pytest.skip("different in docutils>=0.22") pub = Publisher(parser=Parser()) try: pub.process_command_line(shlex.split(file_params.description or "")) @@ -36,6 +41,7 @@ def test_cmdline(file_params: ParamTestData): writer_name="pseudoxml", settings_overrides=settings, ) + output = normalize_doctree_xml(output) warnings = report_stream.getvalue() if warnings: output += "\n" + warnings diff --git a/tests/test_renderers/test_myst_refs.py b/tests/test_renderers/test_myst_refs.py index ac69f771..fcdfd619 100644 --- a/tests/test_renderers/test_myst_refs.py +++ b/tests/test_renderers/test_myst_refs.py @@ -1,4 +1,7 @@ +import sys + import pytest +from conftest import normalize_doctree_xml from sphinx.util.console import strip_colors from sphinx_pytest.plugin import CreateDoctree @@ -7,13 +10,29 @@ "test_name,text,should_warn", [ ("null", "", False), - ("missing", "[](ref)", True), + pytest.param( + "missing", + "[](ref)", + True, + marks=pytest.mark.skipif( + sys.platform == "win32", + reason="Path separators differ on Windows", + ), + ), ("doc", "[](index)", False), ("doc_with_extension", "[](index.md)", False), ("doc_nested", "[*text*](index)", False), ("ref", "(ref)=\n# Title\n[](ref)", False), ("ref_nested", "(ref)=\n# Title\n[*text*](ref)", False), - ("duplicate", "(index)=\n# Title\n[](index)", True), + pytest.param( + "duplicate", + "(index)=\n# Title\n[](index)", + True, + marks=pytest.mark.skipif( + sys.platform == "win32", + reason="Path separators differ on Windows", + ), + ), ("ref_colon", "(ref:colon)=\n# Title\n[](ref:colon)", False), ], ) @@ -37,7 +56,7 @@ def test_parse( doctree["source"] = "root/index.md" doctree.attributes.pop("translation_progress", None) - outcome = doctree.pformat() + outcome = normalize_doctree_xml(doctree.pformat()) if result.warnings.strip(): outcome += "\n\n" + strip_colors(result.warnings.strip()) file_regression.check(outcome, basename=test_name, extension=".xml") diff --git a/tests/test_sphinx/conftest.py b/tests/test_sphinx/conftest.py index cdb2d999..ddace0d6 100644 --- a/tests/test_sphinx/conftest.py +++ b/tests/test_sphinx/conftest.py @@ -41,6 +41,7 @@ def test_basic(app, status, warning, get_sphinx_app_output): from docutils import nodes from myst_parser._compat import findall +from tests.conftest import normalize_doctree_xml SOURCE_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "sourcedirs")) @@ -84,8 +85,6 @@ def read( for clearer_div in doc_div.findAll("div", {"class": "clearer"}): clearer_div.decompose() text = doc_div.prettify() - # changed in sphinx 7.2 - text = text.replace('"Link to this', '"Permalink to this') for find, rep in (replace or {}).items(): text = text.replace(find, rep) file_regression.check(text, extension=regress_ext, encoding="utf8") @@ -127,7 +126,7 @@ def read( node.attributes.pop("translated", None) if regress: - text = doctree.pformat() # type: str + text = normalize_doctree_xml(doctree.pformat()) # type: str for find, rep in (replace or {}).items(): text = text.replace(find, rep) if rstrip_lines: diff --git a/tests/test_sphinx/sourcedirs/includes/index.md b/tests/test_sphinx/sourcedirs/includes/index.md index 9957b6d9..3f3c4cf0 100644 --- a/tests/test_sphinx/sourcedirs/includes/index.md +++ b/tests/test_sphinx/sourcedirs/includes/index.md @@ -14,7 +14,7 @@ ```{include} include_code.py :code: python -:number-lines: 0 +:number-lines: 1 ``` ```{include} include_literal.txt diff --git a/tests/test_sphinx/test_sphinx_builds.py b/tests/test_sphinx/test_sphinx_builds.py index 8beb8748..0276b247 100644 --- a/tests/test_sphinx/test_sphinx_builds.py +++ b/tests/test_sphinx/test_sphinx_builds.py @@ -7,12 +7,14 @@ import os import re +import sys from pathlib import Path import pytest -import sphinx from sphinx.util.console import strip_colors +from tests.conftest import normalize_doctree_xml + SOURCE_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "sourcedirs")) @@ -41,10 +43,7 @@ def test_basic( app, docname="content", regress=True, - replace={ - # changed in sphinx 7.1 - '<literal classes="code" language="">': '<literal classes="code">', - }, + replace={}, ) finally: get_sphinx_app_doctree( @@ -52,10 +51,7 @@ def test_basic( docname="content", resolve=True, regress=True, - replace={ - # changed in sphinx 7.1 - '<literal classes="code" language="">': '<literal classes="code">', - }, + replace={}, ) get_sphinx_app_output( app, @@ -162,9 +158,6 @@ def test_references_singlehtml( regress=True, replace={ "other\\other.md": "other/other.md", - # changed in sphinx 7.3 - '="#document-index': '="index.html#document-index', - '="#document-other': '="index.html#document-other', }, ) @@ -252,6 +245,39 @@ def test_extended_syntaxes( ) +@pytest.mark.sphinx( + buildername="text", + srcdir=os.path.join(SOURCE_DIR, "extended_syntaxes"), + freshenv=True, +) +def test_extended_syntaxes_text( + app, + status, + warning, + get_sphinx_app_output, + monkeypatch, + file_regression, +): + """test setting addition configuration values.""" + from myst_parser.mdit_to_docutils.sphinx_ import SphinxRenderer + + monkeypatch.setattr(SphinxRenderer, "_random_label", lambda self: "mock-uuid") + app.build() + assert "build succeeded" in status.getvalue() # Build succeeded + warnings = warning.getvalue().strip() + assert warnings == "" + content = get_sphinx_app_output( + app, + buildername="text", + filename="index.txt", + ) + file_regression.check(content) + + +@pytest.mark.skipif( + sys.platform == "win32", + reason="original_uri attribute handling differs on Windows", +) @pytest.mark.sphinx( buildername="html", srcdir=os.path.join(SOURCE_DIR, "includes"), freshenv=True ) @@ -417,7 +443,9 @@ def test_substitutions( try: get_sphinx_app_doctree(app, docname="index", regress=True) file_regression.check( - get_sphinx_app_doctree(app, docname="other").pformat(), + normalize_doctree_xml( + get_sphinx_app_doctree(app, docname="other").pformat() + ), extension=".other.xml", ) finally: @@ -444,11 +472,13 @@ def test_gettext( output = re.sub(r"POT-Creation-Date: [0-9: +-]+", "POT-Creation-Date: ", output) output = re.sub(r"Copyright \(C\) [0-9]{4}", "Copyright (C) XXXX", output) - if sphinx.version_info < (7, 4): - output = output.replace("Python ", "Project name not set ") file_regression.check(output, extension=".pot") +@pytest.mark.skipif( + sys.platform == "win32", + reason="Unicode encoding issues on Windows", +) @pytest.mark.sphinx( buildername="html", srcdir=os.path.join(SOURCE_DIR, "gettext"), @@ -486,14 +516,7 @@ def test_gettext_html( filename="index.html", regress_html=True, regress_ext=".html", - replace={ - # upstream bug https://github.com/sphinx-doc/sphinx/issues/11689 - '"Permalink to this heading"': '"Lien permanent vers cette rubrique"', - # which was fixed to a different translation in sphinx 7.3 - '"Lien vers cette rubrique"': '"Lien permanent vers cette rubrique"', - # changed in docutils>0.19 - ' role="note">': ' role="doc-footnote">', - }, + replace={}, ) @@ -528,8 +551,6 @@ def test_gettext_additional_targets( output = re.sub(r"POT-Creation-Date: [0-9: +-]+", "POT-Creation-Date: ", output) output = re.sub(r"Copyright \(C\) [0-9]{4}", "Copyright (C) XXXX", output) - if sphinx.version_info < (7, 4): - output = output.replace("Python ", "Project name not set ") file_regression.check(output, extension=".pot") @@ -554,6 +575,10 @@ def test_mathjax_warning( ) +@pytest.mark.skipif( + sys.platform == "win32", + reason="Unicode encoding issues on Windows", +) @pytest.mark.sphinx( buildername="html", srcdir=os.path.join(SOURCE_DIR, "fieldlist"), @@ -577,20 +602,7 @@ def test_fieldlist_extension( app, docname="index", regress=True, - replace={ - # changed in sphinx 7.2 for desc_sig_name node - 'classes="n n"': 'classes="n"', - # changed in sphinx 7.2 for desc_parameterlist node - 'multi_line_parameter_list="False" ': "", - # changed in sphinx 7.1 (but fixed in 7.2) for desc_signature/desc_name nodes - 'classes="sig sig-object sig sig-object"': 'classes="sig sig-object"', - 'classes="sig-name descname sig-name descname"': 'classes="sig-name descname"', - # changed in sphinx 7.2 (#11533) - ( - 'no-contents-entry="False" no-index="False" ' - 'no-index-entry="False" no-typesetting="False" ' - ): "", - }, + replace={}, ) finally: get_sphinx_app_output( @@ -614,9 +626,6 @@ def test_texinfo(app, status, warning): assert warnings == "" -@pytest.mark.skipif( - sphinx.version_info < (7, 2, 5), reason="include-read event added in sphinx 7.2.5" -) @pytest.mark.sphinx( buildername="html", srcdir=os.path.join(SOURCE_DIR, "includes"), diff --git a/tests/test_sphinx/test_sphinx_builds/test_basic.html b/tests/test_sphinx/test_sphinx_builds/test_basic.html index b3e99c79..a87ea38a 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_basic.html +++ b/tests/test_sphinx/test_sphinx_builds/test_basic.html @@ -29,7 +29,7 @@ </span> <h1> Header - <a class="headerlink" href="#header" title="Permalink to this heading"> + <a class="headerlink" href="#header" title="Link to this heading"> ¶ </a> </h1> @@ -79,7 +79,7 @@ <h1> <span class="caption-text"> Caption </span> - <a class="headerlink" href="#id1" title="Permalink to this image"> + <a class="headerlink" href="#id1" title="Link to this image"> ¶ </a> </p> @@ -120,7 +120,7 @@ <h1> <div class="math notranslate nohighlight" id="equation-eq-label"> <span class="eqno"> (1) - <a class="headerlink" href="#equation-eq-label" title="Permalink to this equation"> + <a class="headerlink" href="#equation-eq-label" title="Link to this equation"> ¶ </a> </span> diff --git a/tests/test_sphinx/test_sphinx_builds/test_basic.resolved.xml b/tests/test_sphinx/test_sphinx_builds/test_basic.resolved.xml index 18605dc4..8e548702 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_basic.resolved.xml +++ b/tests/test_sphinx/test_sphinx_builds/test_basic.resolved.xml @@ -53,7 +53,7 @@ https://www.google.com <paragraph> <strong> - <literal classes="code"> + <literal classes="code" language=""> a=1{`} <paragraph> <math> diff --git a/tests/test_sphinx/test_sphinx_builds/test_basic.xml b/tests/test_sphinx/test_sphinx_builds/test_basic.xml index 72397484..7dfd0cd7 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_basic.xml +++ b/tests/test_sphinx/test_sphinx_builds/test_basic.xml @@ -53,7 +53,7 @@ https://www.google.com <paragraph> <strong> - <literal classes="code"> + <literal classes="code" language=""> a=1{`} <paragraph> <math> diff --git a/tests/test_sphinx/test_sphinx_builds/test_commonmark_only.html b/tests/test_sphinx/test_sphinx_builds/test_commonmark_only.html index 381996f7..c993ac66 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_commonmark_only.html +++ b/tests/test_sphinx/test_sphinx_builds/test_commonmark_only.html @@ -4,7 +4,7 @@ <section id="test"> <h1> Test - <a class="headerlink" href="#test" title="Permalink to this heading"> + <a class="headerlink" href="#test" title="Link to this heading"> ¶ </a> </h1> diff --git a/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.html b/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.html index 7657e922..962b72cc 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.html +++ b/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.html @@ -4,7 +4,7 @@ <section class="tex2jax_ignore mathjax_ignore" id="test"> <h1> Test - <a class="headerlink" href="#test" title="Permalink to this heading"> + <a class="headerlink" href="#test" title="Link to this heading"> ¶ </a> </h1> @@ -22,7 +22,7 @@ <h1> <div class="math notranslate nohighlight" id="equation-2"> <span class="eqno"> (1) - <a class="headerlink" href="#equation-2" title="Permalink to this equation"> + <a class="headerlink" href="#equation-2" title="Link to this equation"> ¶ </a> </span> @@ -135,7 +135,7 @@ <h1> <span class="caption-text"> This is a caption in **Markdown** </span> - <a class="headerlink" href="#target" title="Permalink to this image"> + <a class="headerlink" href="#target" title="Link to this image"> ¶ </a> </p> @@ -150,7 +150,7 @@ <h1> <span class="caption-text"> This is a caption in **Markdown** </span> - <a class="headerlink" href="#other-target" title="Permalink to this image"> + <a class="headerlink" href="#other-target" title="Link to this image"> ¶ </a> </p> diff --git a/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.xml b/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.xml index f2a03817..ae04d66e 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.xml +++ b/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.xml @@ -26,7 +26,7 @@ \begin{equation} b=2 \end{equation} - <math_block docname="index" label="True" nowrap="False" number="True" xml:space="preserve"> + <math_block docname="index" label="True" no-wrap="False" nowrap="False" number="True" xml:space="preserve"> c=3 d=4 diff --git a/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes_text.txt b/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes_text.txt new file mode 100644 index 00000000..63cc2918 --- /dev/null +++ b/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes_text.txt @@ -0,0 +1,63 @@ +Test +**** + +*disabled* + +a=1 + + x=5 + + x=5 + +$ a=1 $ + +a + + c=3 + + b + + \begin{equation} b=2 \end{equation} + + c=3 d=4 + +Term **1** + Definition *1* + + second paragraph + +Term 2 + Definition 2a + + Definition 2b + +Term 3 + code block + + quote + + other + +term + definition + +other term + other definition + +*other term* + + [image: fun-fish][image]This is a caption in **Markdown** + + [image: fishy][image]This is a caption in **Markdown** + +Hallo *there* + +linkify URL: www.example.com + +* hallo + +* there + +Numbered code block: + + type Result = "pass" | "fail" diff --git a/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.html b/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.html index 8548f3d6..2285e23a 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.html +++ b/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.html @@ -4,7 +4,7 @@ <section id="test"> <h1> Test - <a class="headerlink" href="#test" title="Permalink to this heading"> + <a class="headerlink" href="#test" title="Link to this heading"> ¶ </a> </h1> @@ -61,7 +61,7 @@ <h1> <span class="sig-paren"> ) </span> - <a class="headerlink" href="#send_message" title="Permalink to this definition"> + <a class="headerlink" href="#send_message" title="Link to this definition"> ¶ </a> </dt> diff --git a/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.xml b/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.xml index 31648faf..7b529cf1 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.xml +++ b/tests/test_sphinx/test_sphinx_builds/test_fieldlist_extension.xml @@ -15,11 +15,11 @@ <paragraph> content <index entries="('pair',\ 'built-in\ function;\ send_message()',\ 'send_message',\ '',\ None)"> - <desc classes="py function" desctype="function" domain="py" nocontentsentry="False" noindex="False" noindexentry="False" objtype="function"> + <desc classes="py function" desctype="function" domain="py" no-contents-entry="False" no-index="False" no-index-entry="False" no-typesetting="False" nocontentsentry="False" noindex="False" noindexentry="False" objtype="function"> <desc_signature _toc_name="send_message()" _toc_parts="('send_message',)" class="" classes="sig sig-object" fullname="send_message" ids="send_message" module="True"> <desc_name classes="sig-name descname" xml:space="preserve"> send_message - <desc_parameterlist xml:space="preserve"> + <desc_parameterlist multi_line_parameter_list="False" multi_line_trailing_comma="True" xml:space="preserve"> <desc_parameter xml:space="preserve"> <desc_sig_name classes="n"> sender diff --git a/tests/test_sphinx/test_sphinx_builds/test_footnotes.html b/tests/test_sphinx/test_sphinx_builds/test_footnotes.html index 9bda2486..804b0a78 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_footnotes.html +++ b/tests/test_sphinx/test_sphinx_builds/test_footnotes.html @@ -4,7 +4,7 @@ <section id="footnotes-with-markdown"> <h1> Footnotes with Markdown - <a class="headerlink" href="#footnotes-with-markdown" title="Permalink to this heading"> + <a class="headerlink" href="#footnotes-with-markdown" title="Link to this heading"> ¶ </a> </h1> diff --git a/tests/test_sphinx/test_sphinx_builds/test_gettext_html.html b/tests/test_sphinx/test_sphinx_builds/test_gettext_html.html index 7e497f62..a77dc404 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_gettext_html.html +++ b/tests/test_sphinx/test_sphinx_builds/test_gettext_html.html @@ -7,7 +7,7 @@ <h1> <strong> gras </strong> - <a class="headerlink" href="#bold-text-1" title="Lien permanent vers cette rubrique"> + <a class="headerlink" href="#bold-text-1" title="Lien vers cette rubrique"> ¶ </a> </h1> diff --git a/tests/test_sphinx/test_sphinx_builds/test_heading_slug_func.html b/tests/test_sphinx/test_sphinx_builds/test_heading_slug_func.html index 67c44157..611ce6c8 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_heading_slug_func.html +++ b/tests/test_sphinx/test_sphinx_builds/test_heading_slug_func.html @@ -4,14 +4,14 @@ <section id="hyphen-1"> <h1> Hyphen - 1 - <a class="headerlink" href="#hyphen-1" title="Permalink to this heading"> + <a class="headerlink" href="#hyphen-1" title="Link to this heading"> ¶ </a> </h1> <section id="dot-1-1"> <h2> Dot 1.1 - <a class="headerlink" href="#dot-1-1" title="Permalink to this heading"> + <a class="headerlink" href="#dot-1-1" title="Link to this heading"> ¶ </a> </h2> diff --git a/tests/test_sphinx/test_sphinx_builds/test_includes.html b/tests/test_sphinx/test_sphinx_builds/test_includes.html index fde9438f..251d0e72 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_includes.html +++ b/tests/test_sphinx/test_sphinx_builds/test_includes.html @@ -4,7 +4,7 @@ <section id="main-title"> <h1> Main Title - <a class="headerlink" href="#main-title" title="Permalink to this heading"> + <a class="headerlink" href="#main-title" title="Link to this heading"> ¶ </a> </h1> @@ -12,7 +12,7 @@ <h1> <section id="markdown"> <h1> Markdown - <a class="headerlink" href="#markdown" title="Permalink to this heading"> + <a class="headerlink" href="#markdown" title="Link to this heading"> ¶ </a> </h1> @@ -26,7 +26,7 @@ <h1> </span> <h2> A Sub-Heading in Include - <a class="headerlink" href="#a-sub-heading-in-include" title="Permalink to this heading"> + <a class="headerlink" href="#a-sub-heading-in-include" title="Link to this heading"> ¶ </a> </h2> @@ -40,7 +40,7 @@ <h2> <section id="a-sub-heading-in-nested-include"> <h2> A Sub-Heading in Nested Include - <a class="headerlink" href="#a-sub-heading-in-nested-include" title="Permalink to this heading"> + <a class="headerlink" href="#a-sub-heading-in-nested-include" title="Link to this heading"> ¶ </a> </h2> @@ -60,7 +60,7 @@ <h2> <span class="caption-text"> Caption </span> - <a class="headerlink" href="#id1" title="Permalink to this image"> + <a class="headerlink" href="#id1" title="Link to this image"> ¶ </a> </p> @@ -82,7 +82,7 @@ <h2> <span class="caption-text"> Caption </span> - <a class="headerlink" href="#id2" title="Permalink to this image"> + <a class="headerlink" href="#id2" title="Link to this image"> ¶ </a> </p> @@ -115,8 +115,8 @@ <h2> </pre> </div> </div> - <pre class="code python literal-block"><small class="ln">0 </small><code data-lineno="0 "><span class="keyword">def</span> <span class="name function">a_func</span><span class="punctuation">(</span><span class="name">param</span><span class="punctuation">):</span><span class="whitespace"> -</span></code><small class="ln">1 </small><code data-lineno="1 "><span class="whitespace"></span> <span class="name builtin">print</span><span class="punctuation">(</span><span class="name">param</span><span class="punctuation">)</span></code></pre> + <pre class="code python literal-block"><small class="ln">1 </small><code data-lineno="1 "><span class="keyword">def</span><span class="whitespace"> </span><span class="name function">a_func</span><span class="punctuation">(</span><span class="name">param</span><span class="punctuation">):</span><span class="whitespace"> +</span></code><small class="ln">2 </small><code data-lineno="2 "><span class="whitespace"></span> <span class="name builtin">print</span><span class="punctuation">(</span><span class="name">param</span><span class="punctuation">)</span></code></pre> <div class="highlight-default notranslate"> <div class="highlight"> <pre><span></span><span class="n">This</span> <span class="n">should</span> <span class="n">be</span> <span class="o">*</span><span class="n">literal</span><span class="o">*</span> @@ -133,7 +133,7 @@ <h2> <section id="a-sub-sub-heading"> <h3> A Sub-sub-Heading - <a class="headerlink" href="#a-sub-sub-heading" title="Permalink to this heading"> + <a class="headerlink" href="#a-sub-sub-heading" title="Link to this heading"> ¶ </a> </h3> diff --git a/tests/test_sphinx/test_sphinx_builds/test_includes.xml b/tests/test_sphinx/test_sphinx_builds/test_includes.xml index 9af883de..c12a9922 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_includes.xml +++ b/tests/test_sphinx/test_sphinx_builds/test_includes.xml @@ -53,6 +53,7 @@ <literal_block classes="code python" source="include_code.py" xml:space="preserve"> <inline classes="keyword"> def + <inline classes="whitespace"> <inline classes="name function"> a_func @@ -75,9 +76,10 @@ ) <literal_block classes="code python" source="include_code.py" xml:space="preserve"> <inline classes="ln"> - 0 + 1 <inline classes="keyword"> def + <inline classes="whitespace"> <inline classes="name function"> a_func @@ -90,7 +92,7 @@ <inline classes="whitespace"> <inline classes="ln"> - 1 + 2 <inline classes="whitespace"> <inline classes="name builtin"> diff --git a/tests/test_sphinx/test_sphinx_builds/test_references.html b/tests/test_sphinx/test_sphinx_builds/test_references.html index 35d1aed7..23da570c 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_references.html +++ b/tests/test_sphinx/test_sphinx_builds/test_references.html @@ -12,7 +12,7 @@ <h1> <span class="math notranslate nohighlight"> \(a=1\) </span> - <a class="headerlink" href="#title-with-nested-a-1" title="Permalink to this heading"> + <a class="headerlink" href="#title-with-nested-a-1" title="Link to this heading"> ¶ </a> </h1> @@ -131,7 +131,7 @@ <h2> <em> anchors </em> - <a class="headerlink" href="#title-anchors" title="Permalink to this heading"> + <a class="headerlink" href="#title-anchors" title="Link to this heading"> ¶ </a> </h2> @@ -200,7 +200,7 @@ <h1> # </span> </code> - <a class="headerlink" href="#intersphinx-via" title="Permalink to this heading"> + <a class="headerlink" href="#intersphinx-via" title="Link to this heading"> ¶ </a> </h1> @@ -267,7 +267,7 @@ <h1> <h1> Image in title <img alt="badge" src="https://shields.io/or/something.svg"/> - <a class="headerlink" href="#image-in-title" title="Permalink to this heading"> + <a class="headerlink" href="#image-in-title" title="Link to this heading"> ¶ </a> </h1> diff --git a/tests/test_sphinx/test_sphinx_builds/test_references_singlehtml.html b/tests/test_sphinx/test_sphinx_builds/test_references_singlehtml.html index ac9ec0b7..bcf33d49 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_references_singlehtml.html +++ b/tests/test_sphinx/test_sphinx_builds/test_references_singlehtml.html @@ -4,7 +4,7 @@ <section id="title"> <h1> Title - <a class="headerlink" href="#title" title="Permalink to this heading"> + <a class="headerlink" href="#title" title="Link to this heading"> ¶ </a> </h1> @@ -14,7 +14,7 @@ <h1> <section id="other-index"> <h2> Other Index - <a class="headerlink" href="#other-index" title="Permalink to this heading"> + <a class="headerlink" href="#other-index" title="Link to this heading"> ¶ </a> </h2> @@ -24,7 +24,7 @@ <h2> <section id="other-title"> <h3> Other Title - <a class="headerlink" href="#other-title" title="Permalink to this heading"> + <a class="headerlink" href="#other-title" title="Link to this heading"> ¶ </a> </h3> @@ -50,7 +50,7 @@ <h3> </a> </p> <p> - <a class="reference internal" href="#title"> + <a class="reference internal" href="#document-index#title"> <span class="std std-ref"> Title </span> @@ -62,7 +62,7 @@ <h3> <section id="other-2-title"> <h3> Other 2 Title - <a class="headerlink" href="#other-2-title" title="Permalink to this heading"> + <a class="headerlink" href="#other-2-title" title="Link to this heading"> ¶ </a> </h3> @@ -99,7 +99,7 @@ <h3> </a> </p> <p> - <a class="reference internal" href="#other-title"> + <a class="reference internal" href="#document-other/other#other-title"> <span class="std std-ref"> Other Title </span> diff --git a/tests/test_sphinx/test_sphinx_builds/test_references_singlehtml.resolved.xml b/tests/test_sphinx/test_sphinx_builds/test_references_singlehtml.resolved.xml index 249957fa..ee5598d2 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_references_singlehtml.resolved.xml +++ b/tests/test_sphinx/test_sphinx_builds/test_references_singlehtml.resolved.xml @@ -3,18 +3,18 @@ <title> Other Title <paragraph> - <reference internal="True" refuri="index.html#document-other/other2"> + <reference internal="True" refuri="#document-other/other2"> <inline classes="doc"> Other 2 Title <paragraph> - <reference internal="True" refuri="index.html#document-other/other2"> + <reference internal="True" refuri="#document-other/other2"> <inline classes="doc doc doc"> Other 2 Title <paragraph> - <reference internal="True" refuri="index.html#document-other/other2"> + <reference internal="True" refuri="#document-other/other2"> <inline classes="std std-doc"> Other 2 Title <paragraph> - <reference internal="True" refuri="index.html#document-index#title"> + <reference internal="True" refuri="#document-index#title"> <inline classes="std std-ref"> Title diff --git a/tox.ini b/tox.ini index 8c4e286f..12b4199e 100644 --- a/tox.ini +++ b/tox.ini @@ -11,15 +11,15 @@ # then then deleting compiled files has been found to fix it: `find . -name \*.pyc -delete` [tox] -envlist = py310-sphinx8 +envlist = py311-sphinx9 [testenv] usedevelop = true -[testenv:py{310,311,312,313}-sphinx{7,8}] +[testenv:py{311,312,313,314}-sphinx{8,9}] deps = - sphinx7: sphinx>=7,<8 sphinx8: sphinx>=8,<9 + sphinx9: sphinx>=9,<10 extras = linkify testing @@ -49,3 +49,15 @@ commands = --re-ignore _build/.* \ --port 0 --open-browser \ -n -b {posargs:html} docs/ docs/_build/{posargs:html} + +[testenv:ruff-check] +dependency_groups = ruff +commands = ruff check {posargs:--fix} + +[testenv:ruff-fmt] +dependency_groups = ruff +commands = ruff format {posargs} + +[testenv:mypy] +dependency_groups = mypy +commands = mypy {posargs:myst_parser}