Merge pull request #27 from executablebooks/add-hide-option

✨ NEW: Add hide option and configuration key

Author: najuzilu

docs/source/index.md

@@ -27,12 +27,12 @@ sphinx-exercise `0.1.1` is in a development stage and may change rapidly.
 The **exercise** directive is
 
 1. automatically numbered
-2. supports options such as `class`, `label`, and `nonumber`
+2. supports options such as `class`, `label`, `nonumber`, and `hidden`
 3. can easily be referenced through `ref` and `numref` roles
 
 The **solution** directive
 
-1. supports options such as `class` and `label`
+1. supports options such as `class`, `label`, and `hidden`
 2. can be referenced through `ref` role
 
 (getting-started)=

docs/source/syntax.md

@@ -18,6 +18,9 @@ An exercise directive can be included using the `exercise` pattern. The directiv
 * `nonumber` : flag (empty)
 
     Turns off exercise auto numbering.
+* `hidden` : flag (empty)
+
+    Removes the directive from the final output.
 
 **Example**
 
@@ -76,6 +79,9 @@ A solution directive can be included using the `solution` pattern. It takes in t
 * `class` : text
 
     Value of the solution’s class attribute which can be used to add custom CSS or JavaScript.
+* `hidden` : flag (empty)
+
+    Removes the directive from the final output.
 
 ```{note}
 The title of the solution directive links directly to the referred directive.
@@ -184,20 +190,31 @@ static int factorial(int n){
 ````
 
 
-## How to Hide Directives
+## Hide or Remove Directives
 
-Directives can be hidden using the `dropdown` class which is available through [Sphinx Book Theme](https://sphinx-book-theme.readthedocs.io/en/latest/index.html). For Sphinx projects, add `"sphinx_book_theme"` to your `html_theme` in the `conf.py` to activate the theme in your Sphinx configuration
+### Hide Content
 
-```md
-...
-html_theme = "sphinx_book_theme"
-...
+The content of directives can be hidden using the `dropdown` class which is available through [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io/en/latest/). For Sphinx projects, add `"sphinx_togglebutton"` to your `extensions` list in `conf.py` to activate the extension
+
+```python
+extensions = [
+    ...
+    "sphinx_togglebutton"
+    ...
+]
 ```
 
-Jupyter Book's default theme is Sphinx Book Theme; therefore, Jupyter Book projects can utilize `dropdown` without having to activate the theme in your Sphinx configuration.
+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.
+To hide the content, simply add `:class: dropdown` as a directive option.
+
+For more use cases see [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io/en/latest/#usage).
 
 **Example**
 
@@ -231,6 +248,36 @@ for any positive integer $n$.
 ```
 ````
 
+### Remove Directives
+
+Any specific directive can be hidden by introducing the `:hidden:` option. For example, the following example will not be displayed
+
+````md
+```{exercise}
+    :hidden:
+
+    This is a hidden exercise directive.
+```
+````
+
+```{exercise}
+    :hidden:
+
+    This is a hidden exercise directive.
+```
+
+### Remove All Solutions
+
+All solution directives can be removed from the final output by setting `hide_solutions` to `True`. For Sphinx projects, add the configuration key in the `conf.py` file. Jupyter Book projects, should set the configuration key in `_config.yml` as follows
+
+```yaml
+...
+sphinx:
+  config:
+    hide_solutions: True
+...
+```
+
 ## Custom CSS or JavaScript
 
 Custom JavaScript scripts and CSS rules will allow you to add additional functionality or customize how elements are displayed. If you'd like to include custom CSS or JavaScript scripts in Jupyter Book, simply add any files ending in `.css` or `.js` under a `_static` folder. Any files under this folder will be automatically copied into the built book.

sphinx_exercise/__init__.py

@@ -340,6 +340,8 @@ def process(self, doctree: nodes.document, docname: str) -> None:
 
 def setup(app: Sphinx) -> Dict[str, Any]:
 
+    app.add_config_value("hide_solutions", False, "env")
+
     app.add_css_file("exercise.css")
     app.connect("build-finished", copy_asset_files)
     app.connect("config-inited", init_numfig)

sphinx_exercise/directive.py

@@ -19,48 +19,48 @@
 logger = logging.getLogger(__name__)
 
 
-class ExerciseDirective(SphinxDirective):
-    """ A custom Sphinx Directive """
+class CustomDirective(SphinxDirective):
+    """ A custom Sphinx directive """
 
-    name = "exercise"
-    has_content = True
-    required_arguments = 0
-    optional_arguments = 1
-    final_argument_whitespace = True
-    option_spec = {
-        "label": directives.unchanged_required,
-        "class": directives.class_option,
-        "nonumber": directives.flag,
-    }
+    name = ""
 
     def run(self) -> List[Node]:
+        if self.name == "solution" and self.env.app.config.hide_solutions:
+            return []
+
         serial_no = self.env.new_serialno()
 
         if not hasattr(self.env, "exercise_list"):
             self.env.exercise_list = {}
 
-        # Take care of class option
         classes, class_name = [self.name], self.options.get("class", "")
         if class_name:
             classes.extend(class_name)
 
-        title_text, _ = "", ""
-        if "nonumber" in self.options:
-            title_text = f"{self.name.title()} "
+        title_text, title = "", ""
+        if self.name == "exercise":
+            if "nonumber" in self.options:
+                title_text = f"{self.name.title()} "
 
-        if self.arguments != []:
-            title_text += f"({self.arguments[0]})"
-            _ += self.arguments[0]
+            if self.arguments != []:
+                title_text += f"({self.arguments[0]})"
+                title += self.arguments[0]
+        else:
+            title_text = f"{self.name.title()} to "
+            target_label = self.arguments[0]
 
         textnodes, messages = self.state.inline_text(title_text, self.lineno)
 
         section = nodes.section(ids=[f"{self.name}-content"])
         self.state.nested_parse(self.content, self.content_offset, section)
 
-        if "nonumber" in self.options:
-            node = unenumerable_node()
+        if self.name == "exercise":
+            if "nonumber" in self.options:
+                node = unenumerable_node()
+            else:
+                node = enumerable_node()
         else:
-            node = enumerable_node()
+            node = linked_node()
 
         node += nodes.title(title_text, "", *textnodes)
         node += section
@@ -88,21 +88,46 @@ def run(self) -> List[Node]:
         node["ids"].append(label)
         node["label"] = label
         node["docname"] = self.env.docname
+        node["hidden"] = True if "hidden" in self.options else False
         node.document = self.state.document
 
+        if self.name == "solution":
+            node["target_label"] = target_label
+
         self.add_name(node)
 
         self.env.exercise_list[label] = {
             "type": self.name,
             "docname": self.env.docname,
             "node": node,
-            "title": _,
+            "title": title,
+            "hidden": node.get("hidden", bool),
         }
+
+        if node.get("hidden", bool):
+            return []
+
         return [node]
 
 
-class SolutionDirective(SphinxDirective):
-    """ A custom Sphinx Directive """
+class ExerciseDirective(CustomDirective):
+    """ A custom exercise directive """
+
+    name = "exercise"
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 1
+    final_argument_whitespace = True
+    option_spec = {
+        "label": directives.unchanged_required,
+        "class": directives.class_option,
+        "nonumber": directives.flag,
+        "hidden": directives.flag,
+    }
+
+
+class SolutionDirective(CustomDirective):
+    """ A custom solution directive """
 
     name = "solution"
     has_content = True
@@ -112,65 +137,5 @@ class SolutionDirective(SphinxDirective):
     option_spec = {
         "label": directives.unchanged_required,
         "class": directives.class_option,
+        "hidden": directives.flag,
     }
-    title_text = f"{name.title()} to "
-
-    def run(self):
-        serial_no = self.env.new_serialno()
-
-        if not hasattr(self.env, "exercise_list"):
-            self.env.exercise_list = {}
-
-        # Take care of class option
-        classes, class_name = [self.name], self.options.get("class", [])
-        if class_name:
-            classes.extend(class_name)
-
-        target_label = self.arguments[0]
-
-        textnodes, messages = self.state.inline_text(self.title_text, self.lineno)
-
-        section = nodes.section(ids=[f"{self.name}-content"])
-        self.state.nested_parse(self.content, self.content_offset, section)
-
-        node = linked_node()
-        node.document = self.state.document
-        node += nodes.title(self.title_text, "", *textnodes)
-        node += section
-
-        label = self.options.get("label", "")
-        if label:
-            self.options["noindex"] = False
-        else:
-            self.options["noindex"] = True
-            label = f"{self.env.docname}-{self.name}-{serial_no}"
-
-        # Duplicate label warning
-        if not label == "" and label in self.env.exercise_list.keys():
-            docpath = self.env.doc2path(self.env.docname)
-            path = docpath[: docpath.rfind(".")]
-            other_path = self.env.doc2path(self.env.exercise_list[label]["docname"])
-            msg = f"duplicate label: {label}; other instance in {other_path}"
-            logger.warning(msg, location=path, color="red")
-            return []
-
-        self.options["name"] = label
-
-        # Set node attributes
-        node["classes"].extend(classes)
-        node["ids"].append(label)
-        node["label"] = label
-        node["docname"] = self.env.docname
-        node["target_label"] = target_label
-        node.document = self.state.document
-
-        self.add_name(node)
-
-        self.env.exercise_list[label] = {
-            "type": self.name,
-            "docname": self.env.docname,
-            "node": node,
-            "title": "",
-        }
-
-        return [node]

tests/books/test-hiddendirectives/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

tests/books/test-hiddendirectives/_enum_duplicatelabel_hidden.rst

@@ -0,0 +1,8 @@
+_enum_duplicatelabel_hidden
+===========================
+
+.. exercise:: duplicate directive 1
+	:label: ex-hidden-number
+	:hidden:
+
+	Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

tests/books/test-hiddendirectives/_enum_hidden.rst

@@ -0,0 +1,8 @@
+_enum_hidden
+============
+
+.. exercise:: duplicate directive 1
+	:label: ex-hidden-number
+	:hidden:
+
+	Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

tests/books/test-hiddendirectives/_linked_enum_hidden.rst

@@ -0,0 +1,9 @@
+_linked_enum_hidden
+===================
+
+
+.. solution:: ex-hidden-number
+	:label: solution-hidden-label
+	:hidden:
+
+	Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

tests/books/test-hiddendirectives/_linked_unenum_hidden.rst

@@ -0,0 +1,9 @@
+_linked_unenum_hidden
+=====================
+
+
+.. solution:: unenum-hidden
+	:label: solution-unenum-label
+	:hidden:
+
+	Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

tests/books/test-hiddendirectives/_unenum_hidden.rst

@@ -0,0 +1,10 @@
+_unenum_hidden
+==============
+
+.. exercise:: Excepteur sint occaecat
+	:label: unenum-hidden
+	:nonumber:
+	:hidden:
+
+
+	Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.