diff --git a/LICENSE b/LICENSE index 582ddf5..19ef4b3 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2020 ExecutableBookProject +Copyright (c) 2024 ExecutableBookProject Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 0106c38..7629fdd 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ We welcome all contributions! See the [EBP Contributing Guide](https://executabl [rtd-badge]: https://readthedocs.org/projects/sphinx-proof/badge/?version=latest [rtd-link]: https://sphinx-proof.readthedocs.io/en/latest/?badge=latest -[github-ci]: https://github.com/executablebooks/sphinx-proof/workflows/continuous-integration/badge.svg?branch=main +[github-ci]: https://github.com/executablebooks/sphinx-proof/workflows/ci.yml/badge.svg?branch=main [github-link]: https://github.com/executablebooks/sphinx-proof [codecov-badge]: https://codecov.io/gh/executablebooks/sphinx-proof/branch/main/graph/badge.svg [codecov-link]: https://codecov.io/gh/executablebooks/sphinx-proof diff --git a/TODO.md b/TODO.md deleted file mode 100644 index d8b5075..0000000 --- a/TODO.md +++ /dev/null @@ -1,6 +0,0 @@ -# ToDo - -- [ ] #8: document how this is different to sphinxcontrib-proof -- [ ] #13: support role placeholders such as number, title, and %s -- [ ] #27: Clicking on ref link leads to wrong location -- [ ] implement LaTeX methods diff --git a/docs/source/conf.py b/docs/source/conf.py index 2484e15..12d05fd 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,7 +1,7 @@ # -- Project information ----------------------------------------------------- project = "sphinx-proof" -copyright = "2020, QuantEcon Developers" +copyright = "2024, QuantEcon Developers" author = "QuantEcon Developers" master_doc = "index" diff --git a/docs/source/index.md b/docs/source/index.md index 3a95a61..0774830 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -16,14 +16,17 @@ zreferences **A proof extension for Sphinx**. This package contains a [Sphinx](http://www.sphinx-doc.org/) extension -for producing proof, theorem, axiom, lemma, definition, criterion, remark, conjecture, -corollary, algorithm, example, property, observation, proposition and assumption directives. +for producing [proof](syntax:proof), [theorem](syntax:theorem), [axiom](syntax:axiom), [lemma](syntax:lemma), +[definition](syntax:definition), [criterion](syntax:criterion), [remark](syntax:remark), +[conjecture](syntax:conjecture),[corollary](syntax:corollary), [algorithm](syntax:algorithm), +[example](syntax:example), [property](syntax:property), [observation](syntax:observation), +[proposition](syntax:proposition) and [assumption](syntax:assumption) directives. **Features**: 1. directives are automatically numbered 2. supports directive options such as `class`, `label`, and `nonumber` -3. can easily be referenced through `prf:ref` role +3. can be referenced through the `prf:ref` role (getting-started)= ## Getting Started diff --git a/docs/source/syntax.md b/docs/source/syntax.md index 044c578..a73c848 100644 --- a/docs/source/syntax.md +++ b/docs/source/syntax.md @@ -4,10 +4,11 @@ This documentation utilized the [Markedly Structured Text (MyST)](https://myst-parser.readthedocs.io/en/latest/index.html) syntax. ``` -This package utilizes a [Sphinx domain](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html) - named "proof" - to describe and link typeset markup objects (theorems, proofs, corollaries, etc.) which we think belong together. All directives follow the pattern `{:}` while all the roles follow the pattern `{:ref}`. To utilize any directive in the `proof` domain follow the pattern `{prf:}`. To reference any directive follow the pattern `{prf:ref}`. +This package utilizes a [Sphinx domain](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html) - named "prf" - to describe and link typeset markup objects (theorems, proofs, corollaries, etc.) which we think belong together. All directives follow the pattern `{:}` while all the roles follow the pattern `{:ref}`. To utilize any directive in the `proof` domain follow the pattern `{prf:}`. To reference any directive follow the pattern `{prf:ref}`. ## Collection of Directives +(syntax:proof)= ### Proofs A proof directive can be included using the `prf:proof` pattern. Unlike the other directives provided through this extension, a proof directive does not include any parameters nor does it require any arguments. A proof directive can easily be referenced through [targets](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing). @@ -68,6 +69,7 @@ Hence $\| y - z \| \geq \| y - \hat y \|$, which completes the proof. _Source:_ [QuantEcon](https://python-advanced.quantecon.org/orth_proj.html#The-Orthogonal-Projection-Theorem) +(syntax:theorem)= ### Theorems A theorem directive can be included using the `prf:theorem` pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported: @@ -139,6 +141,7 @@ _Source:_ [QuantEcon](https://python-advanced.quantecon.org/orth_proj.html#The-O You can refer to a theorem using the `{prf:ref}` role like: ```{prf:ref}`my-theorem` ```, which will replace the reference with the theorem number like so: {prf:ref}`my-theorem`. When an explicit text is provided, this caption will serve as the title of the reference. For example, ```{prf:ref}`Orthogonal-Projection-Theorem ` ``` will produce: {prf:ref}`Orthogonal-Projection-Theorem `. +(syntax:axiom)= ### Axioms An axiom directive can be included using the `prf:axiom` pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported: @@ -178,6 +181,7 @@ _Source:_ {cite}`economic-dynamics-book` You can refer to an axiom using the `{prf:ref}` role like: ```{prf:ref}`my-axiom` ```, which will replace the reference with the axiom number like so: {prf:ref}`my-axiom`. When an explicit text is provided, this caption will serve as the title of the reference. +(syntax:lemma)= ### Lemmas A lemma directive can be included using the `prf:lemma` pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported: @@ -229,6 +233,7 @@ _Source:_ [QuantEcon](https://python-advanced.quantecon.org/robustness.html#Appe You can refer to a lemma using the `{prf:ref}` role like: ```{prf:ref}`my-lemma` ```, which will replace the reference with the lemma number like so: {prf:ref}`my-lemma`. When an explicit text is provided, this caption will serve as the title of the reference. +(syntax:definition)= ### Definitions A definition directive can be included using the `prf:definition` pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported: @@ -282,6 +287,7 @@ _Source:_ [QuantEcon](https://python-advanced.quantecon.org/von_neumann_model.ht You can refer to a definition using the `{prf:ref}` role like: ```{prf:ref}`my-definition` ```, which will replace the reference with the definition number like so: {prf:ref}`my-definition`. When an explicit text is provided, this caption will serve as the title of the reference. +(syntax:criterion)= ### Criteria A criterion directive can be included using the `prf:criterion` pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported: @@ -331,6 +337,7 @@ _Source:_ [Wikipedia](https://en.wikipedia.org/wiki/Equidistributed_sequence#Wey You can refer to a criterion using the `{prf:ref}` role like: ```{prf:ref}`weyls-criterion` ```, which will replace the reference with the criterion number like so: {prf:ref}`weyls-criterion`. When an explicit text is provided, this caption will serve as the title of the reference. +(syntax:remark)= ### Remarks A remark directive can be included using the `prf:remark` pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported: @@ -391,6 +398,7 @@ _Source:_ [QuantEcon](https://python-advanced.quantecon.org/black_litterman.html You can refer to a remark using the `{prf:ref}` role like: ```{prf:ref}`my-remark` ```, which will replace the reference with the remark number like so: {prf:ref}`my-remark`. When an explicit text is provided, this caption will serve as the title of the reference. +(syntax:conjecture)= ### Conjectures **Example** @@ -415,6 +423,7 @@ This is a dummy conjecture to illustrate that one can use math in titles. You can refer to a conjecture using the `{prf:ref}` role like: ```{prf:ref}`my-conjecture` ```, which will replace the reference with the conjecture number like so: {prf:ref}`my-conjecture`. When an explicit text is provided, this caption will serve as the title of the reference. +(syntax:corollary)= ### Corollaries A corollary directive can be included using the `prf:corollary` pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported: @@ -456,6 +465,7 @@ _Source:_ [QuantEcon](https://python-intro.quantecon.org/_static/lecture_specifi You can refer to a corollary using the `{prf:ref}` role like: ```{prf:ref}`my-corollary` ```, which will replace the reference with the corollary number like so: {prf:ref}`my-corollary`. When an explicit text is provided, this caption will serve as the title of the reference. +(syntax:algorithm)= ### Algorithms @@ -519,6 +529,7 @@ _Source:_ [Wikipedia](https://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algor You can refer to a algorithms using the `{prf:ref}` role like: ```{prf:ref}`my-algorithm` ```, which will replace the reference with the algorithm number like so: {prf:ref}`my-algorithm`. When an explicit text is provided, this caption will serve as the title of the reference. +(syntax:example)= ### Examples An example directive can be included using the `prf:example` pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported: @@ -588,6 +599,7 @@ _Source:_ [QuantEcon](https://python.quantecon.org/lq_inventories.html#Example-2 You can refer to an example using the `{prf:ref}` role like: ```{prf:ref}`my-example` ```, which will replace the reference with the example number like so: {prf:ref}`my-example`. When an explicit text is provided, this caption will serve as the title of the reference. +(syntax:property)= ### Properties A property directive can be included using the `prf:property` pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported: @@ -624,6 +636,8 @@ This is a dummy property to illustrate the directive. You can refer to a property using the `{prf:ref}` role like: ```{prf:ref}`my-property` ```, which will replace the reference with the property number like so: {prf:ref}`my-property`. When an explicit text is provided, this caption will serve as the title of the reference. + +(syntax:observation)= ### Observations An observation directive can be included using the `prf:observation` pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported: @@ -660,6 +674,7 @@ This is a dummy observation directive. You can refer to an observation using the `{prf:ref}` role like: ```{prf:ref}`my-observation` ```, which will replace the reference with the observation number like so: {prf:ref}`my-observation`. When an explicit text is provided, this caption will serve as the title of the reference. +(syntax:proposition)= ### Propositions A proposition directive can be included using the `prf:proposition` pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported: @@ -697,6 +712,7 @@ This is a dummy proposition directive. You can refer to a proposition using the `{prf:ref}` role like: ```{prf:ref}`my-proposition` ```, which will replace the reference with the proposition number like so: {prf:ref}`my-proposition`. When an explicit text is provided, this caption will serve as the title of the reference. +(syntax:assumption)= ### Assumptions An assumption directive can be included using the `prf:assumption` pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported: diff --git a/sphinx_proof/domain.py b/sphinx_proof/domain.py index 714bdcb..289e51a 100644 --- a/sphinx_proof/domain.py +++ b/sphinx_proof/domain.py @@ -92,6 +92,33 @@ def __init__(self, env: "BuildEnvironment") -> None: for node, settings in env.app.registry.enumerable_nodes.items(): self.enumerable_nodes[node] = settings + def resolve_any_xref( + self, + env: BuildEnvironment, + fromdocname: str, + builder: Builder, + target: str, + node: pending_xref, + contnode: Element, + ): + """ + Support for resolve_any_xref as required by myst-parser. + Roles are forwarded to the resolve_xref method, and only non None results + are returned. + """ + results = [] + for role in self.roles: + res = self.resolve_xref( + env, fromdocname, builder, role, target, node, contnode + ) + if res is None: + continue + else: + # https://www.sphinx-doc.org/en/master/extdev/domainapi.html#sphinx.domains.Domain.resolve_any_xref + res = (role.name, res) + results.append(res) + return results + def resolve_xref( self, env: BuildEnvironment, diff --git a/tox.ini b/tox.ini index 111200c..8563616 100644 --- a/tox.ini +++ b/tox.ini @@ -24,7 +24,7 @@ commands = pytest {posargs} [testenv:docs-{update,clean}] extras = rtd -whitelist_externals = rm +allowlist_externals = rm commands = clean: rm -rf docs/build sphinx-build {posargs} -b html docs/source docs/build/html