Add more info on Python code and the bin directory

Author: benmwebb

doc/.template.coding.ipynb

@@ -263,6 +263,15 @@
     "(For reference, the whole file is also available [at GitHub](https://github.com/salilab/imp_coding_tutorial/tree/main/modules/foo/pyext/swig.i-in))."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "> You can also add arbitrary Python code to your module. This is added to the `swig.i-in` file using the SWIG `%pythoncode` directive. See the [PMI module](https://github.com/salilab/pmi/blob/develop/pyext/swig.i-in) for an example.\n",
+    ">\n",
+    "> You can also add entire Python submodules by adding Python files to the `pyext/src` subdirectory. For example the file `pyext/src/my_python.py` can be imported in Python using `import IMP.foo.my_python`. This is also [used in the PMI module](https://github.com/salilab/pmi/tree/develop/pyext/src)."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -361,6 +370,17 @@
     "(For reference, the whole file is also available [at GitHub](https://github.com/salilab/imp_coding_tutorial/tree/main/modules/foo/test/test_restraint.py))."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# bin directory (command line tools) {#bin}\n",
+    "\n",
+    "IMP modules can include command line tools. We don't include any such tools in this module, but to add a tool, add a C++ or Python file to the `bin` directory. The tool will be compiled if needed and then installed with the rest of IMP in the binary directory (e.g. `/usr/local/bin`). See the [FoXS module](https://github.com/salilab/imp/tree/develop/modules/foxs/bin) for an example C++ command line tool and the [em module](https://github.com/salilab/imp/tree/develop/modules/em/bin) for example Python tools.\n",
+    "\n",
+    "> Usually command line tools are all installed in the same directory, so take care to give each program a fairly unique name so as not to conflict with other IMP programs or the operating system itself."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -387,6 +407,15 @@
     "(For reference, the whole file is also available [at GitHub](https://github.com/salilab/imp_coding_tutorial/tree/main/modules/foo/dependencies.py))."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Pure Python modules {#pyonly}\n",
+    "\n",
+    "If there is no C++ code in your module at all - i.e. it is pure Python - then you can speed up building of your module by marking it as Python only. This is done by adding `python_only = True` to the `dependencies.py` file. SWIG is not used in Python-only modules; instead, put any Python code you want in the top-level module in the `pyext/src/__init__.py` file. For an example, see the [IMP.test module](https://github.com/salilab/imp/tree/develop/modules/test). See the [IMP manual](@ref pyonlymod) for more information."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -579,7 +608,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.4"
+   "version": "3.12.1"
   }
  },
  "nbformat": 4,

doc/coding.ipynb

@@ -17,7 +17,9 @@
         " - [pyext directory (Python interface)](#pyext)\n",
         " - [Documentation](#documentation)\n",
         " - [test directory (test cases)](#test)\n",
+        " - [bin directory (command line tools)](#bin)\n",
         " - [Dependencies](#depends)\n",
+        " - [Pure Python modules](#pyonly)\n",
         " - [Source control](#sourcecontrol)\n",
         " - [Build and test](#buildtest)\n",
         " - [Automatic testing](#autotest)\n",
@@ -276,6 +278,15 @@
         "(For reference, the whole file is also available [at GitHub](https://github.com/salilab/imp_coding_tutorial/tree/main/modules/foo/pyext/swig.i-in))."
       ]
     },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "> You can also add arbitrary Python code to your module. This is added to the `swig.i-in` file using the SWIG `%pythoncode` directive. See the [PMI module](https://github.com/salilab/pmi/blob/develop/pyext/swig.i-in) for an example.\n",
+        ">\n",
+        "> You can also add entire Python submodules by adding Python files to the `pyext/src` subdirectory. For example the file `pyext/src/my_python.py` can be imported in Python using `import IMP.foo.my_python`. This is also [used in the PMI module](https://github.com/salilab/pmi/tree/develop/pyext/src)."
+      ]
+    },
     {
       "cell_type": "markdown",
       "metadata": {},
@@ -374,6 +385,17 @@
         "(For reference, the whole file is also available [at GitHub](https://github.com/salilab/imp_coding_tutorial/tree/main/modules/foo/test/test_restraint.py))."
       ]
     },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# bin directory (command line tools)<a id=\"bin\"></a>\n",
+        "\n",
+        "IMP modules can include command line tools. We don't include any such tools in this module, but to add a tool, add a C++ or Python file to the `bin` directory. The tool will be compiled if needed and then installed with the rest of IMP in the binary directory (e.g. `/usr/local/bin`). See the [FoXS module](https://github.com/salilab/imp/tree/develop/modules/foxs/bin) for an example C++ command line tool and the [em module](https://github.com/salilab/imp/tree/develop/modules/em/bin) for example Python tools.\n",
+        "\n",
+        "> Usually command line tools are all installed in the same directory, so take care to give each program a fairly unique name so as not to conflict with other IMP programs or the operating system itself."
+      ]
+    },
     {
       "cell_type": "markdown",
       "metadata": {},
@@ -400,6 +422,15 @@
         "(For reference, the whole file is also available [at GitHub](https://github.com/salilab/imp_coding_tutorial/tree/main/modules/foo/dependencies.py))."
       ]
     },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Pure Python modules<a id=\"pyonly\"></a>\n",
+        "\n",
+        "If there is no C++ code in your module at all - i.e. it is pure Python - then you can speed up building of your module by marking it as Python only. This is done by adding `python_only = True` to the `dependencies.py` file. SWIG is not used in Python-only modules; instead, put any Python code you want in the top-level module in the `pyext/src/__init__.py` file. For an example, see the [IMP.test module](https://github.com/salilab/imp/tree/develop/modules/test). See the [IMP manual](https://integrativemodeling.org/2.20.1/doc/manual/pyonlymod.html) for more information."
+      ]
+    },
     {
       "cell_type": "markdown",
       "metadata": {},
@@ -592,7 +623,7 @@
       "name": "python",
       "nbconvert_exporter": "python",
       "pygments_lexer": "ipython3",
-      "version": "3.11.4"
+      "version": "3.12.1"
     }
   },
   "nbformat": 4,