Merge pull request #2231 from Tobychev/classes-doc

Added a bit of clarification of how important `classes` attribute is to the tool doc
cta-observatory · Jan 24, 2023 · 2021ad1 · 2021ad1
2 parents 14ea3ba + 29e5d16
commit 2021ad1
Show file tree

Hide file tree

Showing 2 changed files with 39 additions and 17 deletions.
diff --git a/docs/ctapipe_api/tools/index.rst b/docs/ctapipe_api/tools/index.rst
@@ -54,8 +54,8 @@ To create a new command-line Tool, follow the following procedure:
 
 1. make a subclass of `ctapipe.core.Tool`
 2. define any user-configurable parameters of the tool
-3. register any configurable `ctapipe.core.Component` lasses
-   that you will use with the Tool via its ``classes`` attribute
+3. register *all* configurable `ctapipe.core.Component` classes
+   that you want to be configured via the Tool via its ``classes`` attribute
 4. use the ``aliases`` attribute to promote any parameters from one of
    the sub-Components to a high-level a command-line parameter (they
    can still be specified using the advanced command-line command

diff --git a/docs/examples/Tools.ipynb b/docs/examples/Tools.ipynb
@@ -10,7 +10,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "from ctapipe.core import Tool, Component, TelescopeComponent\n",
@@ -59,7 +61,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "class MyComponent(Component):\n",
@@ -73,6 +77,8 @@
     "\n",
     "# in order to have 2 of the same components at once\n",
     "class SecondaryMyComponent(MyComponent):\n",
+    "    \"\"\"A second component\"\"\"\n",
+    "\n",
     "    pass\n",
     "\n",
     "\n",
@@ -112,7 +118,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "MyComponent()"
@@ -178,7 +186,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Now create an executable Tool that contains the Components"
+    "## Now create an executable Tool that contains the Components\n",
+    "Note that all the components we wish to be configured via the tool must be added to the `classes` attribute."
    ]
   },
   {
@@ -242,7 +251,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "tool = MyTool()\n",
@@ -269,7 +280,8 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "scrolled": false
+    "scrolled": true,
+    "tags": []
    },
    "outputs": [],
    "source": [
@@ -296,7 +308,7 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "scrolled": false
+    "tags": []
    },
    "outputs": [],
    "source": [
@@ -373,7 +385,7 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "scrolled": true
+    "tags": []
    },
    "outputs": [],
    "source": [
@@ -450,7 +462,8 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "scrolled": true
+    "scrolled": true,
+    "tags": []
    },
    "outputs": [],
    "source": [
@@ -535,7 +548,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "tool.setup()\n",
@@ -545,7 +560,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "outputs": [],
    "source": [
     "tool.comp2"
@@ -587,13 +604,18 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "scrolled": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "print(tool.generate_config_file())"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
@@ -612,7 +634,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.13"
+   "version": "3.9.15"
   }
  },
  "nbformat": 4,