[DOCS] add suggested changes for docs

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,39 +25,35 @@ 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`:
 
 ```bash
 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 <project>` 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.

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
+```
+

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
-```

docs/source/zreferences.md

@@ -0,0 +1,4 @@
+# References
+
+```{bibliography} references.bib
+```