diff --git a/docs/requirements.txt b/docs/requirements.txt index f18e05b..987ee96 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,5 @@ sphinx>=3.0 sphinx-book-theme -myst-nb +myst-parser sphinxcontrib-bibtex +sphinx_togglebutton diff --git a/docs/source/conf.py b/docs/source/conf.py index b8a3ffe..809b52d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -11,7 +11,12 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named "sphinx.ext.*") or your custom # ones. -extensions = ["sphinx_proof", "myst_parser", "sphinxcontrib.bibtex"] +extensions = [ + "sphinx_proof", + "myst_parser", + "sphinxcontrib.bibtex", + "sphinx_togglebutton", +] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] diff --git a/docs/source/syntax.md b/docs/source/syntax.md index 9116d87..51411fc 100644 --- a/docs/source/syntax.md +++ b/docs/source/syntax.md @@ -6,7 +6,9 @@ This documentation utilized the [Markedly Structured Text (MyST)](https://myst-p 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}`. -## Proofs +## Collection of Directives + +### 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). @@ -66,7 +68,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) -## Theorems +### 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: @@ -133,11 +135,11 @@ The vector $\hat y$ is called the **orthogonal projection** of $y$ onto $S$. _Source:_ [QuantEcon](https://python-advanced.quantecon.org/orth_proj.html#The-Orthogonal-Projection-Theorem) -### Referencing Theorems +#### Referencing Theorems 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 `. -## Axioms +### Axioms An axiom 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: @@ -171,12 +173,12 @@ Every Cauchy sequence on the real line is convergent. _Source:_ {cite}`economic-dynamics-book` -### Referencing Axioms +#### Referencing Axioms 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. -## Lemmas +### 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: @@ -222,12 +224,12 @@ K(\hat F, \theta) = (\theta I - C'\hat P C)^{-1} C' \hat P (A - B \hat F) _Source:_ [QuantEcon](https://python-advanced.quantecon.org/robustness.html#Appendix) -### Referencing Lemmas +#### Referencing Lemmas 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. -## Definitions +### 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: @@ -276,11 +278,11 @@ $$ _Source:_ [QuantEcon](https://python-advanced.quantecon.org/von_neumann_model.html#Duality) -### Referencing Definitions +#### Referencing Definitions 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. -## Criteria +### 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: @@ -324,12 +326,12 @@ and only if for all non-zero integers $m$, _Source:_ [Wikipedia](https://en.wikipedia.org/wiki/Equidistributed_sequence#Weyl's_criterion) -### Referencing Criteria +#### Referencing Criteria 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. -## Remarks +### 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: @@ -384,12 +386,12 @@ This property is called **spherical symmetry** (see p 81. in Leamer _Source:_ [QuantEcon](https://python-advanced.quantecon.org/black_litterman.html) -### Referencing Remarks +#### Referencing Remarks 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. -## Conjectures +### Conjectures **Example** @@ -409,11 +411,11 @@ This is a dummy conjecture to illustrate that one can use math in titles. ``` `````` -### Referencing Conjectures +#### Referencing Conjectures 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. -## Corollaries +### 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: @@ -449,12 +451,12 @@ that $\vert \vert A \vert \vert < 1$. _Source:_ [QuantEcon](https://python-intro.quantecon.org/_static/lecture_specific/linear_models/iteration_notes.pdf) -### Referencing Corollaries +#### Referencing Corollaries 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. -## Algorithms +### Algorithms An algorithm directive can be included using the `prf:algorithm` pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported: @@ -512,12 +514,12 @@ An algorithm directive can be included using the `prf:algorithm` pattern. The di _Source:_ [Wikipedia](https://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algorithm) -### Referencing Algorithms +#### Referencing Algorithms 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. -## Examples +### 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: @@ -581,12 +583,12 @@ ex2.simulate(x0) _Source:_ [QuantEcon](https://python.quantecon.org/lq_inventories.html#Example-2) -### Referencing Examples +#### Referencing Examples 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. -## Properties +### 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: @@ -618,11 +620,11 @@ This is a dummy property to illustrate the directive. ``` `````` -### Referencing Properties +#### Referencing Properties 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. -## Observations +### 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: @@ -654,11 +656,11 @@ This is a dummy observation directive. ``` `````` -### Referencing Observations +#### Referencing Observations 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. -## Propositions +### 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: @@ -690,6 +692,48 @@ This is a dummy proposition directive. ``` `````` -### Referencing Propositions +#### Referencing Propositions 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. + +## How to Hide Content + +Directive content can be hidden using the `dropdown` class which is available through [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io/en/latest/). If your project utilizes the [MyST-NB](https://myst-nb.readthedocs.io/en/latest/) extension, there is no need to activate `sphinx-togglebutton` since it is already bundled with `MyST-NB`. + +For Sphinx projects, add `"sphinx_togglebutton"` to your `extensions` list in `conf.py` to activate the extension + +```python +extensions = [ + ... + "sphinx_togglebutton" + ... +] +``` + +For Jupyter Book projects, add `sphinx_togglebutton` under `extra_extensions` + +```yaml +sphinx: + extra_extensions: + - sphinx_togglebutton +``` + +To hide the directive, simply add `:class: dropdown` as a directive option. + +**Example** + +```{prf:theorem} +:class: dropdown + +This is an example of how to hide the content of a directive. +``` + +**MyST Syntax**: + +```` +```{prf:theorem} +:class: dropdown + +This is an example of how to hide the content of a directive. +``` +```` diff --git a/setup.py b/setup.py index 0fb25ce..cf96a03 100644 --- a/setup.py +++ b/setup.py @@ -33,6 +33,7 @@ "sphinx-book-theme", "sphinxcontrib-bibtex", "myst-parser", + "sphinx_togglebutton", ], } diff --git a/sphinx_proof/_static/proof.css b/sphinx_proof/_static/proof.css index 4925e06..51e0c9f 100644 --- a/sphinx_proof/_static/proof.css +++ b/sphinx_proof/_static/proof.css @@ -17,18 +17,6 @@ /********************************************* * Main body * *********************************************/ -div.proof { - padding-left: 0rem !important; - padding-right: 0rem !important; -} - -div.proof p.admonition-title { - padding: .6rem .4rem .6rem 1.6rem; -} - -div.proof div.section { - padding: .6rem 1rem; -} /* Remove content box */ div.proof p.admonition-title::before { @@ -39,8 +27,8 @@ div.proof p.admonition-title::before { * Proof * *********************************************/ div#proof{ - padding: .6rem .8rem !important; - border-left: .2rem solid var(--grey-border-color); + padding: .4rem .6rem .4rem 2rem !important; + border-color: var(--grey-border-color); background-color: none; } @@ -48,7 +36,7 @@ div#proof{ * Theorem * *********************************************/ div.theorem { - border-left: .2rem solid var(--note-border-color); + border-color: var(--note-border-color); background-color: var(--note-title-color); } @@ -60,7 +48,7 @@ div.theorem p.admonition-title { * Axiom * *********************************************/ div.axiom { - border-left: .2rem solid var(--hint-border-color); + border-color: var(--hint-border-color); background-color: var(--hint-title-color); } @@ -72,7 +60,7 @@ div.axiom p.admonition-title { * Criterion * *********************************************/ div.criterion { - border-left: .2rem solid var(--caution-border-color); + border-color: var(--caution-border-color); background-color: var(--caution-title-color); } @@ -84,7 +72,7 @@ div.criterion p.admonition-title { * Lemma * *********************************************/ div.lemma { - border-left: .2rem solid var(--hint-border-color); + border-color: var(--hint-border-color); background-color: var(--hint-title-color); } @@ -96,7 +84,7 @@ div.lemma p.admonition-title { * Definition * *********************************************/ div.definition { - border-left: .2rem solid var(--note-border-color); + border-color: var(--note-border-color); background-color: var(--note-title-color); } @@ -108,7 +96,7 @@ div.definition p.admonition-title { * Remark * *********************************************/ div.remark { - border-left: .2rem solid var(--warning-border-color); + border-color: var(--warning-border-color); background-color: var(--warning-title-color); } @@ -120,7 +108,7 @@ div.remark p.admonition-title { * Conjecture * *********************************************/ div.conjecture { - border-left: .2rem solid var(--hint-border-color); + border-color: var(--hint-border-color); background-color: var(--hint-title-color); } @@ -132,7 +120,7 @@ div.conjecture p.admonition-title { * Corollary * *********************************************/ div.corollary { - border-left: .2rem solid var(--caution-border-color); + border-color: var(--caution-border-color); background-color: var(--caution-title-color); } @@ -163,7 +151,7 @@ div.algorithm div.section { * Example * *********************************************/ div.example { - border-left: .2rem solid var(--hint-border-color); + border-color: var(--hint-border-color); background-color: none; } @@ -175,7 +163,7 @@ div.example p.admonition-title { * Property * *********************************************/ div.property { - border-left: .2rem solid var(--caution-border-color); + border-color: var(--caution-border-color); background-color: var(--caution-title-color); } @@ -187,7 +175,7 @@ div.property p.admonition-title { * Observation * *********************************************/ div.observation { - border-left: .2rem solid var(--hint-border-color); + border-color: var(--hint-border-color); background-color: var(--hint-title-color); } @@ -199,7 +187,7 @@ div.observation p.admonition-title { * Proposition * *********************************************/ div.proposition { - border-left: .2rem solid var(--note-border-color); + border-color: var(--note-border-color); background-color: var(--note-title-color); }