From 8bc197c35524600cd04e8ddced0740482e32b52d Mon Sep 17 00:00:00 2001 From: mmcky Date: Mon, 31 Aug 2020 11:17:24 +1000 Subject: [PATCH] add suggested changes for docs --- docs/source/index.md | 46 +++++++++++++++++++++----------------- docs/source/install.md | 21 +++++++++++++++++ docs/source/syntax.md | 37 +++++++++++++++--------------- docs/source/zreferences.md | 4 ++++ 4 files changed, 68 insertions(+), 40 deletions(-) create mode 100644 docs/source/install.md create mode 100644 docs/source/zreferences.md diff --git a/docs/source/index.md b/docs/source/index.md index 24ba082..1d2466c 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,5 +1,13 @@ # sphinxcontrib-prettyproof +```{toctree} +:hidden: + +install +syntax +zreferences +``` + [![Documentation Status](https://readthedocs.org/projects/sphinxcontrib-prettyproof/badge/?version=latest)](https://sphinxcontrib-prettyproof.readthedocs.io/en/latest/?badge=latest) **A proof extension for Sphinx**. @@ -17,14 +25,8 @@ sphinxcontrib-prettyproof `0.0.2` is in a development stage and may change rapid 2. supports directive options such as `class`, `label`, and `nonumber` 3. can easily be referenced through `proof:ref` role - -```{toctree} -:hidden: - -syntax -``` - -## Get started +(getting-started)= +## Getting Started To get started with `sphinxcontrib-prettyproof`, first install it through `pip`: @@ -32,24 +34,26 @@ To get started with `sphinxcontrib-prettyproof`, first install it through `pip`: pip install sphinxcontrib-prettyproof ``` -then, add `sphinxcontrib.prettyproof` to your sphinx `extensions` in the `conf.py` +### JuputerBook Project -```python -... -extensions = ["sphinxcontrib.prettyproof"] -... +Add `sphinxcontrib.prettyproof` to your [extra_extensions](https://jupyterbook.org/advanced/sphinx.html#custom-sphinx-extensions) config in `_config.yml` + +```yaml +sphinx: + extra_extensions: + - sphinxcontrib.prettyproof ``` -## Installation +you may then use `jb build ` and the extension will be used by your `JupyterBook` project. +### Sphinx Project -**Step 1:** To install the extension you need to clone the repository then run: +Add `sphinxcontrib.prettyproof` to your sphinx `extensions` in the `conf.py` -```bash -python setup.py install +```python +... +extensions = ["sphinxcontrib.prettyproof"] +... ``` -**Step 2:** Add `sphinxcontrib.prettyproof` to your sphinx `extensions` in the `conf.py` - -**Step 3:** Build using ``make html`` - +you may then build using `make html` and the extension will be used by your `Sphinx` project. diff --git a/docs/source/install.md b/docs/source/install.md new file mode 100644 index 0000000..f8451bc --- /dev/null +++ b/docs/source/install.md @@ -0,0 +1,21 @@ +# Installation + +The **recommended** method of installation for most users is via `pip` as detailed +in {ref}`getting-started`. + +You can also install directly from the repository to get the latest `development` version + +## Latest Version + +You can clone the repository: + +```bash +git clone https://github.com/najuzilu/sphinxcontrib-prettyproof +``` + +then run: + +```bash +python setup.py install +``` + diff --git a/docs/source/syntax.md b/docs/source/syntax.md index e5e5ce3..542b2a4 100644 --- a/docs/source/syntax.md +++ b/docs/source/syntax.md @@ -72,10 +72,10 @@ A theorem directive can be included using the `proof:theorem` pattern. The direc Turns off theorem auto numbering. -```{math} -\DeclareMathOperator*{\argmax}{arg\,max} -\DeclareMathOperator*{\argmin}{arg\,min} -``` + ```{math} + \DeclareMathOperator*{\argmax}{arg\,max} + \DeclareMathOperator*{\argmin}{arg\,min} + ``` **Example** @@ -101,7 +101,7 @@ The vector $\hat y$ is called the **orthogonal projection** of $y$ onto $S$. **MyST Syntax** -`````` +``````md ````{proof:theorem} Orthogonal-Projection-Theorem :label: my-theorem @@ -153,7 +153,7 @@ Every Cauchy sequence on the real line is convergent. **MyST Syntax** -`````` +``````md ```{proof:axiom} Completeness of $\mathbb{R}$ :label: my-axiom @@ -198,7 +198,7 @@ K(\hat F, \theta) = (\theta I - C'\hat P C)^{-1} C' \hat P (A - B \hat F) **MyST Syntax** -`````` +``````md ````{proof:lemma} :label: my-lemma @@ -251,7 +251,7 @@ $$ **MyST Syntax** -`````` +``````md ````{proof:definition} :label: my-definition @@ -289,7 +289,7 @@ A criteria directive can be included using the `proof:criteria` pattern. The dir **Example** ````{proof:criteria} Weyl's criterion -:label: my-criteria +:label: weyls-criteria Weyl's criterion states that the sequence $a_n$ is equidistributed modulo $1$ if and only if for all non-zero integers $m$, @@ -301,9 +301,9 @@ and only if for all non-zero integers $m$, **MyST Syntax** -`````` +``````md ````{proof:criteria} Weyl's criterion -:label: my-criteria +:label: weyls-criteria Weyl's criterion states that the sequence $a_n$ is equidistributed modulo $1$ if and only if for all non-zero integers $m$, @@ -318,7 +318,7 @@ _Source:_ [Wikipedia](https://en.wikipedia.org/wiki/Equidistributed_sequence#Wey ### Referencing Criterion -You can refer to a criteria using the `{proof:ref}` role like: ```{proof:ref}`my-criteria` ```, which will replace the reference with the criteria number like so: {proof:ref}`my-criteria`. When an explicit text is provided, this caption will serve as the title of the reference. +You can refer to a criteria using the `{proof:ref}` role like: ```{proof:ref}`weyls-criteria` ```, which will replace the reference with the criteria number like so: {proof:ref}`weyls-criteria`. When an explicit text is provided, this caption will serve as the title of the reference. ## Remarks @@ -385,12 +385,16 @@ You can refer to a remark using the `{proof:ref}` role like: ```{proof:ref}`my-r **Example** -```{proof:conjecture} +```{proof:conjecture} Fake $\gamma$ conjecture +This is a dummy conjecture to illustrate that one can use math in titles. ``` **MyST Syntax** -`````` +``````md +```{proof:conjecture} Fake $\gamma$ conjecture +This is a dummy conjecture to illustrate that one can use math in titles. +``` `````` _Source:_ @@ -550,8 +554,3 @@ _Source:_ [QuantEcon](https://python-programming.quantecon.org/functions.html#Ex ### Referencing Exercises You can refer to a exercises using the `{proof:ref}` role like: ```{proof:ref}`my-exercise` ```, which will replace the reference with the exercise number like so: {proof:ref}`my-exercise`. When an explicit text is provided, this caption will serve as the title of the reference. - ---- - -```{bibliography} references.bib -``` \ No newline at end of file diff --git a/docs/source/zreferences.md b/docs/source/zreferences.md new file mode 100644 index 0000000..c6cfd30 --- /dev/null +++ b/docs/source/zreferences.md @@ -0,0 +1,4 @@ +# References + +```{bibliography} references.bib +``` \ No newline at end of file