docs

Author: jph00

.gitignore

@@ -1,3 +1,4 @@
+meta/
 dlgs/
 archived/
 SOLVEIT.ipynb

README.md

@@ -14,12 +14,10 @@ Python packaging standards ([PEP
 lives in the standard `[project]` section, while nbdev-specific settings
 go in `[tool.nbdev]`.
 
-**Migrating from nbdev2:** Run
-[`nbdev_migrate_config`](https://nbdev.fast.ai/api/migrate.html#nbdev_migrate_config)
-in your project root to automatically convert your `settings.ini` to
-`pyproject.toml` and update your GitHub Actions workflows to use
-nbdev3-compatible versions. Your existing notebooks and code don’t need
-any changes.
+**Migrating from nbdev2:** Run `nbdev-migrate-config` in your project
+root to automatically convert your `settings.ini` to `pyproject.toml`
+and update your GitHub Actions workflows to use nbdev3-compatible
+versions. Your existing notebooks and code don’t need any changes.
 
 `nbdev` is a notebook-driven development platform. Simply write
 notebooks with lightweight markup and get high-quality documentation,
@@ -42,8 +40,7 @@ practices because tests and documentation are first class.
 - **Two-way sync between notebooks and plaintext source code** allowing
   you to use your IDE for code navigation or quick edits. Sync is
   robust: each exported cell is tagged with its unique notebook cell ID,
-  so [`nbdev_update`](https://nbdev.fast.ai/api/sync.html#nbdev_update)
-  always updates the correct cell
+  so `nbdev-update` always updates the correct cell
 - **Tests** written as ordinary notebook cells are run in parallel with
   a single command
 - **Continuous integration** out-of-the-box with [GitHub
@@ -85,47 +82,47 @@ walkthrough](https://youtu.be/67FdzLSt4aA) with coding sections sped up
 using the `unsilence` Python library – it’s 27 minutes faster, but a bit
 harder to follow.
 
-You can also run `nbdev_help` from the terminal to see the full list of
+You can also run `nbdev-help` from the terminal to see the full list of
 available commands:
 
 ``` python
-!nbdev_help
+!nbdev-help
 ```
 
-    nb_export                 Export a single nbdev notebook to a python script.
-    nbdev_bump_version        Increment version in __init__.py by one
-    nbdev_changelog           Create a CHANGELOG.md file from closed and labeled GitHub issues
-    nbdev_clean               Clean all notebooks in `fname` to avoid merge conflicts
-    nbdev_conda               Create a `meta.yaml` file ready to be built into a package, and optionally build and upload it
-    nbdev_contributing        Create CONTRIBUTING.md from contributing_nb (defaults to 'contributing.ipynb' if present). Skips if the file doesn't exist.
-    nbdev_create_config       Create a pyproject.toml config file.
-    nbdev_docs                Create Quarto docs and README.md
-    nbdev_export              Export notebooks in `path` to Python modules
-    nbdev_filter              A notebook filter for Quarto
-    nbdev_fix                 Create working notebook from conflicted notebook `nbname`
-    nbdev_help                Show help for all console scripts
-    nbdev_install             Install Quarto and the current library
-    nbdev_install_hooks       Install Jupyter and git hooks to automatically clean, trust, and fix merge conflicts in notebooks
-    nbdev_install_quarto      Install latest Quarto on macOS or Linux, prints instructions for Windows
-    nbdev_merge               Git merge driver for notebooks
-    nbdev_migrate             Convert all markdown and notebook files in `path` from v1 to v2
-    nbdev_migrate_config      Migrate settings.ini to pyproject.toml
-    nbdev_new                 Create an nbdev project.
-    nbdev_prepare             Export, test, and clean notebooks, and render README if needed
-    nbdev_preview             Preview docs locally
-    nbdev_proc_nbs            Process notebooks in `path` for docs rendering
-    nbdev_pypi                Create and upload Python package to PyPI
-    nbdev_readme              Create README.md from readme_nb (index.ipynb by default)
-    nbdev_release_both        Release both conda and PyPI packages
-    nbdev_release_gh          Calls `nbdev_changelog`, lets you edit the result, then pushes to git and calls `nbdev_release_git`
-    nbdev_release_git         Tag and create a release in GitHub for the current version
-    nbdev_requirements        Writes a `requirements.txt` file to `directory` based on pyproject.toml.
-    nbdev_sidebar             Create sidebar.yml
-    nbdev_test                Test in parallel notebooks matching `path`, passing along `flags`
-    nbdev_trust               Trust notebooks matching `fname`.
-    nbdev_update              Propagate change in modules matching `fname` to notebooks that created them
-    nbdev_update_license      Allows you to update the license of your project.
-    watch_export              Use `nb_export` on ipynb files in `nbs` directory on changes using nbdev config if available
+    nb-export                 Export a single nbdev notebook to a python script.
+    nbdev-bump-version        Increment version in __init__.py by one
+    nbdev-changelog           Create a CHANGELOG.md file from closed and labeled GitHub issues
+    nbdev-clean               Clean all notebooks in `fname` to avoid merge conflicts
+    nbdev-conda               Create a `meta.yaml` file ready to be built into a package, and optionally build and upload it
+    nbdev-contributing        Create CONTRIBUTING.md from contributing_nb (defaults to 'contributing.ipynb' if present). Skips if the file doesn't exist.
+    nbdev-create-config       Create a pyproject.toml config file.
+    nbdev-docs                Create Quarto docs and README.md
+    nbdev-export              Export notebooks in `path` to Python modules
+    nbdev-filter              A notebook filter for Quarto
+    nbdev-fix                 Create working notebook from conflicted notebook `nbname`
+    nbdev-help                Show help for all console scripts
+    nbdev-install             Install Quarto and the current library
+    nbdev-install-hooks       Install Jupyter and git hooks to automatically clean, trust, and fix merge conflicts in notebooks
+    nbdev-install-quarto      Install latest Quarto on macOS or Linux, prints instructions for Windows
+    nbdev-merge               Git merge driver for notebooks
+    nbdev-migrate             Convert all markdown and notebook files in `path` from v1 to v2
+    nbdev-migrate-config      Migrate settings.ini to pyproject.toml
+    nbdev-new                 Create an nbdev project.
+    nbdev-prepare             Export, test, and clean notebooks, and render README if needed
+    nbdev-preview             Preview docs locally
+    nbdev-proc-nbs            Process notebooks in `path` for docs rendering
+    nbdev-pypi                Create and upload Python package to PyPI
+    nbdev-readme              Create README.md from readme_nb (index.ipynb by default)
+    nbdev-release-both        Release both conda and PyPI packages
+    nbdev-release-gh          Calls `nbdev_changelog`, lets you edit the result, then pushes to git and calls `nbdev_release_git`
+    nbdev-release-git         Tag and create a release in GitHub for the current version
+    nbdev-requirements        Writes a `requirements.txt` file to `directory` based on pyproject.toml.
+    nbdev-sidebar             Create sidebar.yml
+    nbdev-test                Test in parallel notebooks matching `path`, passing along `flags`
+    nbdev-trust               Trust notebooks matching `fname`.
+    nbdev-update              Propagate change in modules matching `fname` to notebooks that created them
+    nbdev-update-license      Allows you to update the license of your project.
+    watch-export              Use `nb_export` on ipynb files in `nbs` directory on changes using nbdev config if available
 
 ## FAQ
 
@@ -204,8 +201,7 @@ strive to abide by generally accepted best practices in open-source
 software development.
 
 Make sure you have `nbdev`’s git hooks installed by running
-[`nbdev_install_hooks`](https://nbdev.fast.ai/api/clean.html#nbdev_install_hooks)
-in the cloned repository.
+`nbdev-install-hooks` in the cloned repository.
 
 ## Copyright
 

nbdev/config.py

@@ -163,11 +163,11 @@ def _find_nbdev_pyproject(path=None):
         if f.exists() and _has_nbdev(f): return f
     for d in [p] + list(p.parents):
         if (d/'settings.ini').exists():
-            raise ValueError(f"Found old settings.ini. Migrate to pyproject.toml using `nbdev_migrate_config`. See https://nbdev.fast.ai/getting_started.html")
+            raise ValueError(f"Found old settings.ini. Migrate to pyproject.toml using `nbdev-migrate-config`. See https://nbdev.fast.ai/getting_started.html")
 
 # %% ../nbs/api/01_config.ipynb #3dac70e0
 nbdev_defaults = dict(nbs_path='nbs', doc_path='_docs', tst_flags='notest', recursive=True, readme_nb='index.ipynb',
-    clean_ids=True, clear_all=False, put_version_in_init=True, jupyter_hooks=False, branch='main',
+    clean_ids=True, clear_all=False, put_version_in_init=True, jupyter_hooks=False, custom_sidebar=False, branch='main',
     doc_procs=[], export_procs=[])
 
 _path_keys = 'lib_path', 'nbs_path', 'doc_path'

nbdev/doclinks.py

@@ -64,7 +64,7 @@ def _iter_py_cells(p):
             nb = ' '.join(parts[:-1])
         else:
             raise ValueError(f"Cell ID required but not found in '{p}' at:\n```\n# %% {top}\n```\n"
-                           "Run `nbdev_export` to regenerate .py files with cell IDs.")
+                           "Run `nbdev-export` to regenerate .py files with cell IDs.")
         if nb=='auto': continue  # Skip auto-generated __all__ cell
         nb_path = (p.parent/nb).resolve()  # NB paths are stored relative to .py file
         if code.endswith('\n'): code=code[:-1]
@@ -147,7 +147,7 @@ def nbdev_export(
     **kwargs):
     "Export notebooks in `path` to Python modules"
     if os.environ.get('IN_TEST',0): return
-    if not is_nbdev(): raise Exception('`nbdev_export` must be called from a directory within a nbdev project.')
+    if not is_nbdev(): raise Exception('`nbdev-export` must be called from a directory within a nbdev project.')
     cfg = get_config()
     procs = procs.split() if procs else cfg.get('export_procs', [])
     procs = [import_obj(p) for p in procs] if procs else None

nbdev/export.py

@@ -53,7 +53,7 @@ def nb_export(nbname:str,        # Filename of notebook
             nm = ifnone(name, getattr(exp, 'default_exp', None) if mod=='#' else mod)
             if not nm:
                 warn(f"Notebook '{nbname}' uses `#| export` without `#| default_exp` cell.\n"
-                     "Note nbdev2 no longer supports nbdev1 syntax. Run `nbdev_migrate` to upgrade.\n"
+                     "Note nbdev2 no longer supports nbdev1 syntax. Run `nbdev-migrate` to upgrade.\n"
                      "See https://nbdev.fast.ai/getting_started.html for more information.")
                 return
             mm = mod_maker(dest=lib_path, name=nm, nb_path=nbname, is_new=bool(name) or mod=='#', solo_nb=solo_nb)

nbdev/quarto.py

@@ -223,7 +223,7 @@ def _doc_mtime_not_older(readme_path, readme_nb_path):
 
 # %% ../nbs/api/14_quarto.ipynb #7b70b5c8
 class _SidebarYmlRemoved:
-    "Context manager for `nbdev_readme` to avoid rendering whole docs website"
+    "Context manager for `nbdev-readme` to avoid rendering whole docs website"
     def __init__(self,path): self._path=path
     def __enter__(self):
         self._yml_path = self._path/'sidebar.yml'

nbdev/release.py

@@ -127,7 +127,7 @@ def release_git(token:str=None):
 def release_gh(
     token:str=None  # Optional GitHub token (otherwise `token` file is used)
 ):
-    "Calls `nbdev_changelog`, lets you edit the result, then pushes to git and calls `nbdev_release_git`"
+    "Calls `nbdev-changelog`, lets you edit the result, then pushes to git and calls `nbdev-release-git`"
     cfg = _find_config()
     Release().changelog()
     subprocess.run([os.environ.get('EDITOR','nano'), cfg.config_path/'CHANGELOG.md'])

nbdev/sync.py

@@ -73,7 +73,7 @@ def _update_mod(py_path, lib_dir):
 @call_parse
 def nbdev_update(fname:str=None): # A Python file name to update
     "Propagate change in modules matching `fname` to notebooks that created them"
-    if fname and fname.endswith('.ipynb'): raise ValueError("`nbdev_update` operates on .py files.  If you wish to convert notebooks instead, see `nbdev_export`.")
+    if fname and fname.endswith('.ipynb'): raise ValueError("`nbdev-update` operates on .py files.  If you wish to convert notebooks instead, see `nbdev-export`.")
     if os.environ.get('IN_TEST',0): return
     cfg = get_config()
     fname = Path(fname or cfg.lib_path)

nbs/api/01_config.ipynb

@@ -74,7 +74,7 @@
    "source": [
     "nbdev is heavily customizeable, thanks to the configuration system defined in this module. There are 2 ways to interact with nbdev's config:\n",
     "\n",
-    "- **In the terminal:** `nbdev_create_config` creates a `pyproject.toml` (if you're starting a new project use `nbdev_new` instead)\n",
+    "- **In the terminal:** `nbdev-create-config` creates a `pyproject.toml` (if you're starting a new project use `nbdev-new` instead)\n",
     "- **In your library:** `get_config` returns a `ConfigToml` object.\n",
     "\n",
     "Read on for more about how these work."
@@ -303,7 +303,7 @@
     "You can create a `pyproject.toml` by passing settings via the command line:\n",
     "\n",
     "```sh\n",
-    "nbdev_create_config --repo nbdev --user fastai --author fastai \\\n",
+    "nbdev-create-config --repo nbdev --user fastai --author fastai \\\n",
     "                    --author_email info@fast.ai --description 'A test project'\n",
     "```\n",
     "\n",
@@ -343,7 +343,7 @@
     "        if f.exists() and _has_nbdev(f): return f\n",
     "    for d in [p] + list(p.parents):\n",
     "        if (d/'settings.ini').exists():\n",
-    "            raise ValueError(f\"Found old settings.ini. Migrate to pyproject.toml using `nbdev_migrate_config`. See https://nbdev.fast.ai/getting_started.html\")"
+    "            raise ValueError(f\"Found old settings.ini. Migrate to pyproject.toml using `nbdev-migrate-config`. See https://nbdev.fast.ai/getting_started.html\")"
    ]
   },
   {
@@ -355,7 +355,7 @@
    "source": [
     "#| export\n",
     "nbdev_defaults = dict(nbs_path='nbs', doc_path='_docs', tst_flags='notest', recursive=True, readme_nb='index.ipynb',\n",
-    "    clean_ids=True, clear_all=False, put_version_in_init=True, jupyter_hooks=False, branch='main',\n",
+    "    clean_ids=True, clear_all=False, put_version_in_init=True, jupyter_hooks=False, custom_sidebar=False, branch='main',\n",
     "    doc_procs=[], export_procs=[])\n",
     "\n",
     "_path_keys = 'lib_path', 'nbs_path', 'doc_path'"
@@ -462,7 +462,7 @@
    "source": [
     "Searches up from `path` until a `pyproject.toml` with `[tool.nbdev]` is found. Unspecified optional settings return defaults.\n",
     "\n",
-    "See `nbdev_create_config` for creating a new config."
+    "See `nbdev-create-config` for creating a new config."
    ]
   },
   {

nbs/api/04_export.ipynb

@@ -142,7 +142,7 @@
     "            nm = ifnone(name, getattr(exp, 'default_exp', None) if mod=='#' else mod)\n",
     "            if not nm:\n",
     "                warn(f\"Notebook '{nbname}' uses `#| export` without `#| default_exp` cell.\\n\"\n",
-    "                     \"Note nbdev2 no longer supports nbdev1 syntax. Run `nbdev_migrate` to upgrade.\\n\"\n",
+    "                     \"Note nbdev2 no longer supports nbdev1 syntax. Run `nbdev-migrate` to upgrade.\\n\"\n",
     "                     \"See https://nbdev.fast.ai/getting_started.html for more information.\")\n",
     "                return\n",
     "            mm = mod_maker(dest=lib_path, name=nm, nb_path=nbname, is_new=bool(name) or mod=='#', solo_nb=solo_nb)\n",