diff --git a/nbdev/doclinks.py b/nbdev/doclinks.py index 7819b55ab..2d07fcdb7 100644 --- a/nbdev/doclinks.py +++ b/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' diff --git a/nbdev/quarto.py b/nbdev/quarto.py index 1472e3a95..d8c13af25 100644 --- a/nbdev/quarto.py +++ b/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 diff --git a/nbs/api/doclinks.ipynb b/nbs/api/doclinks.ipynb index b4874fec7..d41773e89 100644 --- a/nbs/api/doclinks.ipynb +++ b/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", diff --git a/nbs/api/quarto.ipynb b/nbs/api/quarto.ipynb index e8904dd81..bbdc74206 100644 --- a/nbs/api/quarto.ipynb +++ b/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]" ] }, { diff --git a/nbs/tutorials/docs_only.ipynb b/nbs/tutorials/docs_only.ipynb new file mode 100644 index 000000000..edf387601 --- /dev/null +++ b/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 \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 +}