Merge pull request #1121 from fastai/nolib-docs

Enable Documentation Only Sites With `nbdev` ( + tutorial )

nbdev/doclinks.py

@@ -83,6 +83,7 @@ def _stor(nm):
 def _build_modidx(dest=None, nbs_path=None, skip_exists=False):
     "Create _modidx.py"
     if dest is None: dest = get_config().lib_path
+    if not Path(dest).exists(): return
     nbs_path = Path(nbs_path or get_config().nbs_path).resolve()
     if os.environ.get('IN_TEST',0): return
     idxfile = dest/'_modidx.py'

nbdev/quarto.py

@@ -179,7 +179,7 @@ def _pre_docs(path=None, n_workers:int=defaults.cpus, **kwargs):
 @delegates(proc_nbs)
 def nbdev_proc_nbs(**kwargs):
     "Process notebooks in `path` for docs rendering"
-    return _pre_docs(**kwargs)[0]
+    _pre_docs(**kwargs)[0]
 
 # %% ../nbs/api/quarto.ipynb 20
 @call_parse

nbs/api/doclinks.ipynb

@@ -224,6 +224,7 @@
     "def _build_modidx(dest=None, nbs_path=None, skip_exists=False):\n",
     "    \"Create _modidx.py\"\n",
     "    if dest is None: dest = get_config().lib_path\n",
+    "    if not Path(dest).exists(): return\n",
     "    nbs_path = Path(nbs_path or get_config().nbs_path).resolve()\n",
     "    if os.environ.get('IN_TEST',0): return\n",
     "    idxfile = dest/'_modidx.py'\n",

nbs/api/quarto.ipynb

@@ -336,7 +336,7 @@
     "@delegates(proc_nbs)\n",
     "def nbdev_proc_nbs(**kwargs):\n",
     "    \"Process notebooks in `path` for docs rendering\"\n",
-    "    return _pre_docs(**kwargs)[0]"
+    "    _pre_docs(**kwargs)[0]"
    ]
   },
   {

nbs/tutorials/docs_only.ipynb

@@ -0,0 +1,84 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0cbcd12b-a30a-4aec-bc64-6ef6e89fc847",
+   "metadata": {},
+   "source": [
+    "# Documentation Only Sites\n",
+    "\n",
+    "> How to create nbdev powered docs without a library!\n",
+    "- order: 9"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "504ef133-7e39-4ef8-a9d5-35a9ca6fbb9b",
+   "metadata": {},
+   "source": [
+    "## Background\n",
+    "\n",
+    "While nbdev is great for authoring software, you may wish to utilize the power of nbdev for the purposes of documenting existing code, or **use various utilities of nbdev without having to write a python library**. For example, you can use the following features of nbdev without creating a python package:\n",
+    "\n",
+    "- Custom [nbdev directives](../explanations/directives.ipynb) such as [`#|hide_line`](../explanations/directives.ipynb#hide_line).\n",
+    "- Testing with `nbdev_test`.\n",
+    "- Automated entity linking with [doclinks](best_practices.ipynb#reference-related-symbols-with-doclinks).\n",
+    "- Rendering API documentation with [docments and show_doc](best_practices.ipynb#document-parameters-with-docments).\n",
+    "\n",
+    "## Setup\n",
+    "\n",
+    "To setup a documentation only site, you can follow these steps:\n",
+    "\n",
+    "1. Create a nbdev repo the usual way, using `nbdev_new`\n",
+    "2. Remove library files\n",
+    "\n",
+    "```bash\n",
+    "rm setup.py .github/workflows/test.yaml nbs/00_core.ipynb\n",
+    "```\n",
+    "\n",
+    "3. Remove your library folder (this will be the `lib_path` field in `settings.ini`):\n",
+    "\n",
+    "```bash\n",
+    "rm -rf <lib_path>\n",
+    "```\n",
+    "\n",
+    "## Usage\n",
+    "\n",
+    "After setting up your project, you can use various nbdev utilities per usual:\n",
+    "\n",
+    "- `nbdev_preview` for previewing your site\n",
+    "- `nbdev_test` for testing your docs locally\n",
+    "- Custom [nbdev directives](../explanations/directives.ipynb) will be available to you (but you must be careful not to use irrelevant ones like `#|export`).\n",
+    "- If you created your nbdev docs site on GitHub, GitHub Actions will publish your docs for you automatically [as described here](../explanations/docs.ipynb#Deploying-Docs-With-GitHub-Actions).\n",
+    "- You can publish your docs on other platforms as described [here](../explanations/docs.ipynb#Deploying-Your-Docs-On-Other-Platforms)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6c7c8ede-f3af-417d-8aa6-7658b5052288",
+   "metadata": {},
+   "source": [
+    "## Demo\n",
+    "\n",
+    "A minimal example of a documentation-only site is located [here](https://github.com/hamelsmu/nolib_nbdev)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "60e597c1-9950-4927-ae5a-79fcc46497bd",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}