Merge pull request #37 from executablebooks/refactor-oct2021

MAINT: review and refactor package

Author: mmcky

.pre-commit-config.yaml

@@ -6,7 +6,9 @@ exclude: >
       \.vscode/settings\.json|
       docs/source/conf\.py|
       tests/test_exercise/.*|
+      tests/test_exercise_references/.*|
       tests/test_solution/.*|
+      tests/test_solution_references/.*|
       tests/test_hiddendirective/.*|
     )$
 

docs/source/conf.py

@@ -1,8 +1,8 @@
 # -- Project information -----------------------------------------------------
 
 project = "sphinx-exercise"
-copyright = "2020, QuantEcon Developers"
-author = "QuantEcon Developers"
+copyright = "2020-2021, Exectuable Book Developers"
+author = "Executable Book Developers"
 master_doc = "index"
 
 

docs/source/developer-design.md

@@ -0,0 +1,88 @@
+# Design of the Package
+
+This page documents some design decisions that were made when building this
+`sphinx` extension.
+
+`sphinx-exercise` includes:
+
+1. `directives`
+2. `nodes`
+3. `post_transforms`
+4. integrations with `sphinx.env`
+
+## Directives
+
+See [](syntax.md) for futher details on the available directives and options
+
+## Nodes
+
+The nodes support the directives:
+
+1. `exercise_node`
+1. `exercise_enumerable_node`
+1. `solution_node`
+
+as well as custom title infrastructure:
+
+1. `exercise_title`
+1. `exercise_subtitle`
+1. `solution_title`
+1. `solution_subtitle`
+
+and support for `:numref:` references to enumerated exercise nodes
+in the LaTeX context by resolving the node title numbering:
+
+1. `exercise_latex_number_reference`
+
+The `title` and `reference` nodes are used internally by the
+`directives` and are then removed in `post_transforms` negating the need
+for any custom `translator` methods. The use
+of custom nodes allows for simpler detection of objects by this
+extension, rather than catering for additional items that may be added by other
+sphinx components.
+
+## Post Transforms
+
+The `post_transforms` run in the following order:
+
+1. UpdateReferencesToEnumerated (priority = 5, before `pending_xref` are resolved)
+2. ResolveTitlesInExercises (priority = 20)
+3. ResolveTitlesInSolutions (priority = 21)
+4. ResolveLinkTextToSolutions (priority = 22)
+
+These `post_transforms` are setup to resolve in `Exercise` -> `Solution` -> `References`
+ordering. Any `:ref:` made to an enumerated `exercise` node are converted into `numref`
+references prior to `pending_xref` objects are resolved by `sphinx`.
+
+This is aligned with most use cases in a document. In the case of `solutions`
+if the target node (title) has not been resolved, this is checked and then resolved
+as required.
+
+**Design Decision:** It was decided to integrate with `:ref:` and `:numref:` roles
+to support both reference styles to `exercise` and `solution` directives.
+The `post_transforms` are required to make adjustments the the `sphinx` abstract
+syntax tree (AST) to support `:numref:` and the resolve `titles`
+in `exercise` and `solution` admonitions. This is required as components of
+`numref` are resolved at the `translator` phase for `html` and is activated
+essentially by default for LaTeX but leaves the numbering to the `LaTeX`
+builder such as `pdflatex`.
+
+## Additional Notes
+
+###  Package Registry `sphinx.env.sphinx_exercise_registry`
+
+This package includes a registry of all `exercise` and `solution`
+nodes that are parsed.
+
+This registry includes nodes referenced by their `label`:
+
+```python
+self.env.sphinx_exercise_registry[label] = {
+    "type": self.name,
+    "docname": self.env.docname,
+    "node": node,
+}
+```
+
+and records the `type`, `docname` where the node is parsed, and
+the `node` object.

docs/source/testing.md renamed to docs/source/developer.md

@@ -1,4 +1,19 @@
-# Testing
+# Developers
+
+Development of this package follows the following conventions and styles.
+
+Design notes and considerations can be found in [](developer-design.md)
+
+## Install
+
+To install the package in `develop` mode:
+
+```shell
+cd sphinx-exercise
+pip install -e .
+```
+
+## Testing
 
 For code tests, `sphinx-exercise` uses [pytest](https://docs.pytest.org/).
 

docs/source/index.md

@@ -5,7 +5,8 @@
 
 install
 syntax
-testing
+developer
+developer-design
 ```
 
 
@@ -20,11 +21,11 @@ for producing exercise and solution directives, for html and pdf outputs.
 
 **Features**:
 
-The **exercise** directive is
+The **exercise** directive is:
 
 1. automatically numbered
 2. supports options such as `class`, `label`, `nonumber`, and `hidden`
-3. can easily be referenced through `ref` and `numref` roles
+3. can be referenced through `ref` and `numref` roles
 
 The **solution** directive
 
@@ -37,7 +38,7 @@ The **solution** directive
 To get started with `sphinx-exercise`, first install it through `pip`:
 
 ```bash
-pip install -e.
+pip install sphinx-exercise
 ```
 
 ### Jupyter-Book Project
@@ -50,7 +51,7 @@ sphinx:
     - sphinx_exercise
 ```
 
-you may then use `jb build <project>` and the extension will be used by your `JupyterBook` project.
+you may then use `jb build <project>` and the extension will be used by your `Jupyter Book` project.
 
 ### Sphinx Project
 

docs/source/syntax.md

@@ -58,20 +58,26 @@ _Source:_ [QuantEcon](https://python-programming.quantecon.org/functions.html#Ex
 
 ### 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`.
+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 be the default "Exercise" or "Exercise {number}" 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]
+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`. In this case it displays the same result as the `{ref}` role as `exerise` notes are (by default) enumerated.
 
+Furthermore, `numref` can take in three additional placeholders for more customized titles:
 
+1. _%s_
+2.  _{number}_ which get replaced by the exercise number, and
+3. _{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. -->
+An example ```{numref}`My custom {number} title and {name}` ``` would resolve to {numref}`My custom {number} title and {name} <my-exercise>`
 
 [^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:
+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 not enumerable as it inherits directly from the linked exercise.
+
+The following options are also supported:
 
 * `label` : text
 
@@ -83,9 +89,6 @@ A solution directive can be included using the `solution` pattern. It takes in t
 
     Removes the directive from the final output.
 
-```{note}
-The title of the solution directive links directly to the referred directive.
-```
 
 **Example**