📚 DOCS: update docs

Author: najuzilu

docs/source/index.md

@@ -5,6 +5,7 @@
 
 install
 syntax
+testing
 ```
 
 [![Documentation Status](https://readthedocs.org/projects/sphinx-exercise/badge/?version=latest)](https://sphinx-exercise.readthedocs.io/en/latest/?badge=latest)
@@ -15,43 +16,50 @@ This package contains a [Sphinx](http://www.sphinx-doc.org/en/master/) extension
 for producing exercise and solution directives.
 
 ```{warning}
-sphinx-exercise `0.0.1` is in a development stage and may change rapidly.
+sphinx-exercise `0.1.0` is in a development stage and may change rapidly.
 ```
 
 **Features**:
 
-1. directives are automatically numbered
-2. supports directive options such as `class`, `label`, and `nonumber`
-3. can easily be referenced through `ref` role
+The **exercise** directive is
+
+1. automatically numbered
+2. supports options such as `class`, `label`, and `nonumber`
+3. can easily be referenced through `ref` and `numref` roles
+
+The **solution** directive
+
+1. supports options such as `class` and `label`
+2. can be referenced through `ref` role
 
 (getting-started)=
 ## Getting Started
 
 To get started with `sphinx-exercise`, first install it through `pip`:
 
 ```bash
-pip install sphinx-exercise
+pip install -e.
 ```
 
 ### JuputerBook Project
 
-Add `sphinx.exercise` to your [extra_extensions](https://jupyterbook.org/advanced/sphinx.html#custom-sphinx-extensions) config in `_config.yml`
+Add `sphinx_exercise` to your [extra_extensions](https://jupyterbook.org/advanced/sphinx.html#custom-sphinx-extensions) config in `_config.yml`
 
 ```yaml
 sphinx:
   extra_extensions:
-    - sphinx.exercise
+    - sphinx_exercise
 ```
 
 you may then use `jb build <project>` and the extension will be used by your `JupyterBook` project.
 
 ### Sphinx Project
 
-Add `sphinx.exercise` to your sphinx `extensions` in the `conf.py`
+Add `sphinx_exercise` to your sphinx `extensions` in the `conf.py`
 
 ```python
 ...
-extensions = ["sphinx.exercise"]
+extensions = ["sphinx_exercise"]
 ...
 ```
 

docs/source/syntax.md

@@ -1,16 +1,17 @@
 # Syntax Guide
 
+
 ```{note}
 This documentation utilized the [Markedly Structured Text (MyST)](https://myst-parser.readthedocs.io/en/latest/index.html) syntax.
 ```
 
-## Exercises
+## Exercise Directive
 
 An exercise directive can be included using the `exercise` pattern. The directive is enumerated by default and can take in an optional title argument. The following options are also supported:
 
 * `label` : text
 
-    A unique identifier for your exercise that you can use to reference it with `{ref}`. Cannot contain spaces or special characters.
+    A unique identifier for your exercise that you can use to reference it with `{ref}` and `{numref}`. Cannot contain spaces or special characters.
 * `class` : text
 
     Value of the exercise’s class attribute which can be used to add custom CSS or JavaScript.
@@ -51,3 +52,133 @@ for any positive integer $n$.
 ``````
 
 _Source:_ [QuantEcon](https://python-programming.quantecon.org/functions.html#Exercise-1)
+
+### Referencing Exercises
+
+You can refer to an exercise using the `{ref}` role like ```{ref}`my-exercise` ```, which will display the title of the exercise directive. In the event that directive does not have a title, the title will default to "Exercise" like so: {ref}`my-exercise`.
+
+Enumerable directives can also be referenced through the `numref` role like ```{numref}`my-exercise` ```, which will display the number of the exercise directive. Referencing the above directive will display {numref}`my-exercise`. Furthermore, `numref` can take in three additional placeholders: _%s_ and _{number}_ which get replaced by the exercise number and _name_ by the exercise title.[^note]
+
+
+
+<!-- You can refer to an exercise using the `{ref}` role like: ```{ref}`my-exercise` ```, which will replace the reference with the exercise number like so: {ref}`my-exercise`. When an explicit text is provided, this caption will serve as the title of the reference. -->
+
+[^note]: If the exercise directive does not have a title, an `invalid numfig format` warning will be displayed during build if the user tries to use the _{name}_ placeholder.
+
+
+## Solution Directive
+
+A solution directive can be included using the `solution` pattern. It takes in the label of the directive it wants to link to as a required argument. Unlike the `exercise` directive, the solution directive is unenumerable. The following options are also supported:
+
+* `label` : text
+
+    A unique identifier for your solution that you can use to reference it with `{ref}`. Cannot contain spaces or special characters.
+* `class` : text
+
+    Value of the solution’s class attribute which can be used to add custom CSS or JavaScript.
+
+```{note}
+The title of the solution directive links directly to the referred directive.
+```
+
+**Example**
+
+````{solution} my-exercise
+:label: my-solution
+
+Here's one solution.
+
+```{code-block} python
+def factorial(n):
+    k = 1
+    for i in range(n):
+        k = k * (i + 1)
+    return k
+
+factorial(4)
+```
+````
+
+**MyST Syntax**
+
+``````md
+````{solution} my-exercise
+:label: my-solution
+
+Here's one solution.
+
+```{code-block} python
+def factorial(n):
+    k = 1
+    for i in range(n):
+        k = k * (i + 1)
+    return k
+
+factorial(4)
+```
+````
+``````
+
+_Source:_ [QuantEcon](https://python-programming.quantecon.org/functions.html#Exercise-1)
+
+
+### Referencing Solutions
+
+You can refer to a solution using the `{ref}` role like: ```{ref}`my-solution` ``` the output of which depends on the attributes of the linked directive. If the linked directive is enumerable, the role will replace the solution reference with the linked directive type and its appropriate number like so: {ref}`my-solution`.
+
+In the event that the directive being referenced is unenumerable, the reference will display its title: {ref}`nfactorial-solution`. Click the toggle to see the supporting directives.
+
+````{toggle}
+
+```{exercise} $n!$ Factorial
+:label: nfactorial
+:nonumber:
+
+Write a function `factorial` such that `factorial(int n)` returns $n!$
+for any positive integer $n$.
+```
+
+```{solution} nfactorial
+:label: nfactorial-solution
+
+Here's a solution in Java.
+
+```{code-block} java
+static int factorial(int n){
+    if (n == 0)
+        return 1;
+    else {
+        return(n * factorial(n-1));
+    }
+}
+```
+````
+
+
+If the title of the linked directive being reference does not exist, it will default to {ref}`nfactorial-notitle-solution`. Click the toggle to see the supporting directives.
+
+````{toggle}
+
+```{exercise}
+:label: nfactorial-notitle
+:nonumber:
+
+Write a function `factorial` such that `factorial(int n)` returns $n!$
+for any positive integer $n$.
+```
+
+```{solution} nfactorial-notitle
+:label: nfactorial-notitle-solution
+
+Here's a solution in Java.
+
+```{code-block} java
+static int factorial(int n){
+    if (n == 0)
+        return 1;
+    else {
+        return(n * factorial(n-1));
+    }
+}
+```
+````

docs/source/testing.md

@@ -0,0 +1,64 @@
+# Testing
+
+For code tests, `sphinx-exercise` uses [pytest](https://docs.pytest.org/).
+
+Run the tests with the following command:
+
+```shell
+>> cd sphinx-exercise
+>> pip install -e .[testing]
+>> pytest
+```
+
+To run the tests in multiple isolated environments, you can also run [tox](https://tox.readthedocs.io/)
+
+```shell
+>> cd sphinx-exercise
+>> tox
+```
+
+To test the build of documentation run
+
+```shell
+>> cd sphinx-exercise
+>> tox docs-update
+```
+
+or
+
+```shell
+>> cd sphinx-exercise/docs
+>> make clean
+>> make html
+```
+
+## Unit Testing
+
+We use [pytest](https://docs.pytest.org/en/latest/) for testing, [pytest-regression](https://pytest-regressions.readthedocs.io/en/latest/) to regenerate expected outcomes of test and [pytest-cov](https://pytest-cov.readthedocs.io/en/latest/) for checking coverage.
+
+To run tests with coverage and an html coverage report:
+
+```bash
+pytest -v --cov=sphinx_exercise --cov-report=html
+```
+
+## Writing Tests
+
+The module `sphinx.testing` is used to run sphinx builds for tests, in a temporary directory.
+
+If creating a new source folder for test files, folder name should start with `test-`.
+Your folder should reside inside the `tests/books` directory, which has been set as the root directory for tests.
+
+The tests should start with:
+
+```python
+@pytest.mark.sphinx('html', testroot="mybook")
+```
+In the above declaration, `html` builder is used. And `mybook` is the source folder which was created with the name `test-mybook` inside `tests/books` folder.
+
+Sphinx Application API is available as a parameter to all the test functions:
+
+```python
+@pytest.mark.sphinx('html', testroot="mybook")
+def mytest(app):
+```