Option to retain magic commands in docs

nbdev/_modidx.py

@@ -175,6 +175,7 @@
                                'nbdev.process.extract_directives': ('api/process.html#extract_directives', 'nbdev/process.py'),
                                'nbdev.process.first_code_ln': ('api/process.html#first_code_ln', 'nbdev/process.py'),
                                'nbdev.process.instantiate': ('api/process.html#instantiate', 'nbdev/process.py'),
+                               'nbdev.process.keep_magics': ('api/process.html#keep_magics', 'nbdev/process.py'),
                                'nbdev.process.nb_lang': ('api/process.html#nb_lang', 'nbdev/process.py'),
                                'nbdev.process.opt_set': ('api/process.html#opt_set', 'nbdev/process.py')},
             'nbdev.processors': { 'nbdev.processors.FilterDefaults': ('api/processors.html#filterdefaults', 'nbdev/processors.py'),

nbdev/process.py

@@ -3,12 +3,14 @@
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/03_process.ipynb.
 
 # %% auto 0
-__all__ = ['langs', 'nb_lang', 'first_code_ln', 'extract_directives', 'opt_set', 'instantiate', 'NBProcessor', 'Processor']
+__all__ = ['langs', 'nb_lang', 'keep_magics', 'first_code_ln', 'extract_directives', 'opt_set', 'instantiate', 'NBProcessor',
+           'Processor']
 
 # %% ../nbs/api/03_process.ipynb
 from .config import *
 from .maker import *
 from .imports import *
+from .config import *
 
 from execnb.nbio import *
 from fastcore.script import *
@@ -50,6 +52,7 @@ def _norm_quarto(s, lang='python'):
 
 # %% ../nbs/api/03_process.ipynb
 _cell_mgc = re.compile(r"^\s*%%\w+")
+def keep_magics(): return get_config().get('keep_magics', False)
 
 def first_code_ln(code_list, re_pattern=None, lang='python'):
     "get first line number where code occurs, where `code_list` is a list of code"

nbdev/processors.py

@@ -176,14 +176,14 @@ def ai_magics(cell):
     "A preprocessor to convert AI magics to markdown"
     if cell.cell_type == 'code' and _aimagics_pattern.search(cell.source):
         cell.cell_type ='markdown'
-        cell.source = '\n'.join(cell.source.splitlines()[1:])
+        if not keep_magics(): cell.source = '\n'.join(cell.source.splitlines()[1:])
 
 # %% ../nbs/api/10_processors.ipynb
 _magics_pattern = re.compile(r'^\s*(%%|%).*', re.MULTILINE)
 
 def clean_magics(cell):
     "A preprocessor to remove cell magic commands"
-    if cell.cell_type == 'code' and not get_config().get('keep_magics', False):
+    if cell.cell_type == 'code' and not keep_magics():
         cell.source = _magics_pattern.sub('', cell.source).strip()
 
 # %% ../nbs/api/10_processors.ipynb

nbs/api/03_process.ipynb

@@ -32,6 +32,7 @@
     "from nbdev.config import *\n",
     "from nbdev.maker import *\n",
     "from nbdev.imports import *\n",
+    "from nbdev.config import *\n",
     "\n",
     "from execnb.nbio import *\n",
     "from fastcore.script import *\n",
@@ -183,6 +184,16 @@
     "test_eq(_norm_quarto('#|not_quarto'), '#|not_quarto')"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "986cd9fa",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "?ifnone"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -192,6 +203,7 @@
    "source": [
     "#|export\n",
     "_cell_mgc = re.compile(r\"^\\s*%%\\w+\")\n",
+    "def keep_magics(): return get_config().get('keep_magics', False)\n",
     "\n",
     "def first_code_ln(code_list, re_pattern=None, lang='python'):\n",
     "    \"get first line number where code occurs, where `code_list` is a list of code\"\n",
@@ -643,11 +655,9 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "af6db102-2447-49ba-94d9-bfebfb48c0f0",
+   "cell_type": "raw",
+   "id": "fc00de03",
    "metadata": {},
-   "outputs": [],
    "source": []
   }
  ],

nbs/api/10_processors.ipynb

@@ -552,7 +552,7 @@
     "    \"A preprocessor to convert AI magics to markdown\"\n",
     "    if cell.cell_type == 'code' and _aimagics_pattern.search(cell.source):\n",
     "        cell.cell_type ='markdown'\n",
-    "        cell.source = '\\n'.join(cell.source.splitlines()[1:])"
+    "        if not keep_magics(): cell.source = '\\n'.join(cell.source.splitlines()[1:])"
    ]
   },
   {
@@ -578,7 +578,7 @@
     "\n",
     "def clean_magics(cell):\n",
     "    \"A preprocessor to remove cell magic commands\"\n",
-    "    if cell.cell_type == 'code' and not get_config().get('keep_magics', False):\n",
+    "    if cell.cell_type == 'code' and not keep_magics():\n",
     "        cell.source = _magics_pattern.sub('', cell.source).strip()"
    ]
   },

nbs/explanations/config.ipynb

@@ -41,14 +41,14 @@
      "text": [
       "[DEFAULT]\r\n",
       "lib_name = nbdev\r\n",
+      "repo = nbdev\r\n",
       "description = Create delightful software with Jupyter Notebooks\r\n",
       "copyright = 2020 onwards, Jeremy Howard\r\n",
       "keywords = nbdev fastai jupyter notebook export\r\n",
       "user = fastai\r\n",
       "author = Jeremy Howard and Hamel Husain\r\n",
       "author_email = j@fast.ai\r\n",
-      "branch = master\r\n",
-      "min_python = 3.7\r\n"
+      "branch = master\r\n"
      ]
     }
    ],
@@ -75,39 +75,43 @@
       "text/markdown": [
        "|    | **Type** | **Default** | **Details** |\n",
        "| -- | -------- | ----------- | ----------- |\n",
-       "| user | str |  | Repo username |\n",
-       "| author | str |  | Package author's name |\n",
-       "| author_email | str |  | Package author's email address |\n",
-       "| description | str |  | Short summary of the package |\n",
+       "| repo | str | None | Repo name |\n",
+       "| branch | str | None | Repo default branch |\n",
+       "| user | str | None | Repo username |\n",
+       "| author | str | None | Package author's name |\n",
+       "| author_email | str | None | Package author's email address |\n",
+       "| description | str | None | Short summary of the package |\n",
        "| path | str | . | Path to create config file |\n",
        "| cfg_name | str | settings.ini | Name of config file to create |\n",
-       "| lib_name | str | None | Package name, defaults to local repo folder name passed to `apply_defaults` |\n",
-       "| branch | str | master | Repo default branch passed to `apply_defaults` |\n",
-       "| git_url | str | https://github.com/%(user)s/%(lib_name)s | Repo URL passed to `apply_defaults` |\n",
-       "| custom_sidebar | bool_arg | False | Use a custom sidebar.yml? passed to `apply_defaults` |\n",
-       "| nbs_path | str | . | Path to notebooks passed to `apply_defaults` |\n",
-       "| lib_path | str | %(lib_name)s | Path to package root passed to `apply_defaults` |\n",
-       "| doc_path | str | _docs | Path to rendered docs passed to `apply_defaults` |\n",
-       "| tst_flags | str |  | Test flags passed to `apply_defaults` |\n",
-       "| version | str | 0.0.1 | Version of this release passed to `apply_defaults` |\n",
-       "| doc_host | str | https://%(user)s.github.io | Hostname for docs passed to `apply_defaults` |\n",
-       "| doc_baseurl | str | /%(lib_name)s | Base URL for docs passed to `apply_defaults` |\n",
-       "| keywords | str | nbdev jupyter notebook python | Package keywords passed to `apply_defaults` |\n",
-       "| license | str | apache2 | License for the package passed to `apply_defaults` |\n",
-       "| copyright | str | None | Copyright for the package, defaults to '`current_year` onwards, `author`' passed to `apply_defaults` |\n",
-       "| status | str | 3 | Development status PyPI classifier passed to `apply_defaults` |\n",
-       "| min_python | str | 3.7 | Minimum Python version PyPI classifier passed to `apply_defaults` |\n",
-       "| audience | str | Developers | Intended audience PyPI classifier passed to `apply_defaults` |\n",
-       "| language | str | English | Language PyPI classifier passed to `apply_defaults` |\n",
-       "| recursive | bool_arg | False | Include subfolders in notebook globs? passed to `apply_defaults` |\n",
-       "| black_formatting | bool_arg | False | Format libraries with black? passed to `apply_defaults` |\n",
-       "| readme_nb | str | index.ipynb | Notebook to export as repo readme passed to `apply_defaults` |\n",
-       "| title | str | %(lib_name)s | Quarto website title passed to `apply_defaults` |\n",
-       "| allowed_metadata_keys | str |  | Preserve the list of keys in the main notebook metadata passed to `apply_defaults` |\n",
-       "| allowed_cell_metadata_keys | str |  | Preserve the list of keys in cell level metadata passed to `apply_defaults` |\n",
-       "| jupyter_hooks | bool | True | Run Jupyter hooks? passed to `apply_defaults` |\n",
-       "| clean_ids | bool | True | Remove ids from plaintext reprs? passed to `apply_defaults` |\n",
-       "| custom_quarto_yml | bool | False | Use a custom _quarto.yml? passed to `apply_defaults` |"
+       "| lib_name | str | %(repo)s | Package name |\n",
+       "| git_url | str | https://github.com/%(user)s/%(repo)s | Repo URL |\n",
+       "| custom_sidebar | bool_arg | False | Use a custom sidebar.yml? |\n",
+       "| nbs_path | Path | nbs | Path to notebooks |\n",
+       "| lib_path | Path | None | Path to package root (default: `repo` with `-` replaced by `_`) |\n",
+       "| doc_path | Path | _docs | Path to rendered docs |\n",
+       "| tst_flags | str | notest | Test flags |\n",
+       "| version | str | 0.0.1 | Version of this release |\n",
+       "| doc_host | str | https://%(user)s.github.io | Hostname for docs |\n",
+       "| doc_baseurl | str | /%(repo)s | Base URL for docs |\n",
+       "| keywords | str | nbdev jupyter notebook python | Package keywords |\n",
+       "| license | str | apache2 | License for the package |\n",
+       "| copyright | str | None | Copyright for the package, defaults to '`current_year` onwards, `author`' |\n",
+       "| status | str | 3 | Development status PyPI classifier |\n",
+       "| min_python | str | 3.7 | Minimum Python version PyPI classifier |\n",
+       "| audience | str | Developers | Intended audience PyPI classifier |\n",
+       "| language | str | English | Language PyPI classifier |\n",
+       "| recursive | bool_arg | True | Include subfolders in notebook globs? |\n",
+       "| black_formatting | bool_arg | False | Format libraries with black? |\n",
+       "| readme_nb | str | index.ipynb | Notebook to export as repo readme |\n",
+       "| title | str | %(lib_name)s | Quarto website title |\n",
+       "| allowed_metadata_keys | str |  | Preserve the list of keys in the main notebook metadata |\n",
+       "| allowed_cell_metadata_keys | str |  | Preserve the list of keys in cell level metadata |\n",
+       "| jupyter_hooks | bool_arg | False | Run Jupyter hooks? |\n",
+       "| clean_ids | bool_arg | True | Remove ids from plaintext reprs? |\n",
+       "| clear_all | bool_arg | False | Remove all cell metadata and cell outputs? |\n",
+       "| cell_number | bool_arg | True | Add cell number to the exported file |\n",
+       "| put_version_in_init | bool_arg | True | Add the version to the main __init__.py in nbdev_export |\n",
+       "| keep_magics | bool | False | Keep magic commands in rendered documentation (useful for AImagic notebooks) |"
       ],
       "text/plain": [
        "<nbdev.showdoc.DocmentTbl>"

settings.ini

@@ -68,4 +68,4 @@ clean_ids = False
 clear_all = False
 cell_number = False
 put_version_in_init = True
-
+keep_magics = False