Skip to content

Commit ced9bb6

Browse files
hamelsmuhamelsmu
committed
refactor modular nbdev
1 parent 8739d03 commit ced9bb6

File tree

1 file changed

+114
-39
lines changed

1 file changed

+114
-39
lines changed

‎nbs/tutorials/modular_nbdev.ipynb‎

Lines changed: 114 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
{
22
"cells": [
3+
{
4+
"cell_type": "raw",
5+
"id": "d3d59c9d-a2f2-4ee8-a05a-000d171aa01d",
6+
"metadata": {},
7+
"source": [
8+
"---\n",
9+
"skip_showdoc: true\n",
10+
"---"
11+
]
12+
},
313
{
414
"cell_type": "markdown",
515
"id": "a2ed9821",
@@ -16,15 +26,102 @@
1626
"id": "a97e9b2c",
1727
"metadata": {},
1828
"source": [
19-
"While `nbdev_new` gets you started with everything you need to create a delightful Python package, **you can also use each of nbdev's components listed below on their own**. You might find this useful if you're porting a large system over to nbdev, or if you'd like to customise the nbdev workflow for your own project. Note that all of the commands below work without a settings.ini file."
29+
"While `nbdev_new` gets you started with everything you need to create a delightful Python package, **you can also use each of nbdev's components listed below on their own**. You might find this useful if you're porting a large system over to nbdev, documenting an existing code base, or if you'd like to customize the nbdev workflow for your own project. Note that all of the commands below work without a `settings.ini` file unless otherwise noted."
30+
]
31+
},
32+
{
33+
"cell_type": "markdown",
34+
"id": "b838f2c9-c24a-457c-9401-40708c5bfba0",
35+
"metadata": {},
36+
"source": [
37+
"## Document Existing Code: `show_doc`\n",
38+
"\n",
39+
"nbdev allows you to document existing code, even code that is not written in nbdev! `nbdev.showdoc.show_doc` allows you to render beautiful API documentation in notebooks and on Quarto sites. For example, you can render API documentation for `numpy.all` like this: \n",
40+
"\n",
41+
"::: {.py-2 .px-3 .mb-4 fig-align=\"center\" .border .rounded .shadow-sm}"
42+
]
43+
},
44+
{
45+
"cell_type": "code",
46+
"execution_count": null,
47+
"id": "bf7cc968-8068-4250-920e-92171bebc17a",
48+
"metadata": {},
49+
"outputs": [
50+
{
51+
"data": {
52+
"text/markdown": [
53+
"---\n",
54+
"\n",
55+
"### all\n",
56+
"\n",
57+
"> all (a, axis=None, out=None, keepdims=<no value>, where=<no value>)\n",
58+
"\n",
59+
"Test whether all array elements along a given axis evaluate to True.\n",
60+
"\n",
61+
"| | **Type** | **Default** | **Details** |\n",
62+
"| -- | -------- | ----------- | ----------- |\n",
63+
"| a | array_like | | Input array or object that can be converted to an array. |\n",
64+
"| axis | NoneType | None | Axis or axes along which a logical AND reduction is performed.<br>The default (``axis=None``) is to perform a logical AND over all<br>the dimensions of the input array. `axis` may be negative, in<br>which case it counts from the last to the first axis.<br><br>.. versionadded:: 1.7.0<br><br>If this is a tuple of ints, a reduction is performed on multiple<br>axes, instead of a single axis or all the axes as before. |\n",
65+
"| out | NoneType | None | Alternate output array in which to place the result.<br>It must have the same shape as the expected output and its<br>type is preserved (e.g., if ``dtype(out)`` is float, the result<br>will consist of 0.0's and 1.0's). See :ref:`ufuncs-output-type` for more<br>details. |\n",
66+
"| keepdims | _NoValueType | <no value> | If this is set to True, the axes which are reduced are left<br>in the result as dimensions with size one. With this option,<br>the result will broadcast correctly against the input array.<br><br>If the default value is passed, then `keepdims` will not be<br>passed through to the `all` method of sub-classes of<br>`ndarray`, however any non-default value will be. If the<br>sub-class' method does not implement `keepdims` any<br>exceptions will be raised. |\n",
67+
"| where | _NoValueType | <no value> | Elements to include in checking for all `True` values.<br>See `~numpy.ufunc.reduce` for details.<br><br>.. versionadded:: 1.20.0 |\n",
68+
"| **Returns** | **ndarray, bool** | | **A new boolean or array is returned unless `out` is specified,<br>in which case a reference to `out` is returned.** |"
69+
],
70+
"text/plain": [
71+
"---\n",
72+
"\n",
73+
"### all\n",
74+
"\n",
75+
"> all (a, axis=None, out=None, keepdims=<no value>, where=<no value>)\n",
76+
"\n",
77+
"Test whether all array elements along a given axis evaluate to True.\n",
78+
"\n",
79+
"| | **Type** | **Default** | **Details** |\n",
80+
"| -- | -------- | ----------- | ----------- |\n",
81+
"| a | array_like | | Input array or object that can be converted to an array. |\n",
82+
"| axis | NoneType | None | Axis or axes along which a logical AND reduction is performed.<br>The default (``axis=None``) is to perform a logical AND over all<br>the dimensions of the input array. `axis` may be negative, in<br>which case it counts from the last to the first axis.<br><br>.. versionadded:: 1.7.0<br><br>If this is a tuple of ints, a reduction is performed on multiple<br>axes, instead of a single axis or all the axes as before. |\n",
83+
"| out | NoneType | None | Alternate output array in which to place the result.<br>It must have the same shape as the expected output and its<br>type is preserved (e.g., if ``dtype(out)`` is float, the result<br>will consist of 0.0's and 1.0's). See :ref:`ufuncs-output-type` for more<br>details. |\n",
84+
"| keepdims | _NoValueType | <no value> | If this is set to True, the axes which are reduced are left<br>in the result as dimensions with size one. With this option,<br>the result will broadcast correctly against the input array.<br><br>If the default value is passed, then `keepdims` will not be<br>passed through to the `all` method of sub-classes of<br>`ndarray`, however any non-default value will be. If the<br>sub-class' method does not implement `keepdims` any<br>exceptions will be raised. |\n",
85+
"| where | _NoValueType | <no value> | Elements to include in checking for all `True` values.<br>See `~numpy.ufunc.reduce` for details.<br><br>.. versionadded:: 1.20.0 |\n",
86+
"| **Returns** | **ndarray, bool** | | **A new boolean or array is returned unless `out` is specified,<br>in which case a reference to `out` is returned.** |"
87+
]
88+
},
89+
"execution_count": null,
90+
"metadata": {},
91+
"output_type": "execute_result"
92+
}
93+
],
94+
"source": [
95+
"#|echo: true\n",
96+
"#|eval: false\n",
97+
"from nbdev.showdoc import show_doc\n",
98+
"from numpy import all\n",
99+
"show_doc(all)"
100+
]
101+
},
102+
{
103+
"cell_type": "markdown",
104+
"id": "4477baba-96ec-4d5f-aa75-a35fbe99a057",
105+
"metadata": {},
106+
"source": [
107+
":::\n",
108+
"\n",
109+
"\n",
110+
"::: {.callout-note}\n",
111+
"\n",
112+
"`show_doc` automatically parses docstrings that are written in the numpy style. For more information [read here](../api/showdoc.ipynb#numpy-docstrings).\n",
113+
"\n",
114+
":::"
20115
]
21116
},
22117
{
23118
"cell_type": "markdown",
24119
"id": "5de0e130",
25120
"metadata": {},
26121
"source": [
27-
"#### `nbdev_test`: Test notebooks"
122+
"## Testing Notebooks: `nbdev_test`\n",
123+
"\n",
124+
"Testing notebooks can be very useful outside of nbdev, especially if you are documenting an existing code base and want to incorporate tests for your docs. The `nbdev_test` CLI utility allows you to accomplish this:"
28125
]
29126
},
30127
{
@@ -50,7 +147,7 @@
50147
"id": "a2a38c4e",
51148
"metadata": {},
52149
"source": [
53-
"#### `nb_export`: Export notebooks to modules"
150+
"## Export Code To Modules: `nb_export`"
54151
]
55152
},
56153
{
@@ -72,21 +169,23 @@
72169
"id": "77673b03",
73170
"metadata": {},
74171
"source": [
75-
"#### `nbdev_install_hooks`: Improve Jupyter/git integration"
172+
"## Jupyter-Git Integration\n",
173+
"\n",
174+
"Jupyter and Git don't normally play well together, especially for things like merge conflicts. We have outlined all of these problems, and our solutions in [this blog post](../blog/posts/2022-08-25-jupyter-git/index.qmd). You can install our merge driver and hooks with the following command: \n",
175+
"\n",
176+
"```bash\n",
177+
"nbdev_install_hooks\n",
178+
"```\n",
179+
"\n",
180+
"We describe what `nbdev_install_hooks` does in detail on [this page](git_friendly_jupyter.ipynb)."
76181
]
77182
},
78183
{
79184
"cell_type": "markdown",
80185
"id": "6f8b49e3",
81186
"metadata": {},
82187
"source": [
83-
"You can install nbdev hooks into any git repo with the terminal command:\n",
84-
"\n",
85-
"```sh\n",
86-
"nbdev_install_hooks\n",
87-
"```\n",
88-
"\n",
89-
"Or directly use any of its underlying commands, for example, to implement your own hooks or extensions:\n",
188+
"You can also directly use any of its underlying commands, for example, to implement your own hooks or extensions:\n",
90189
"\n",
91190
"- `nbdev_clean`\n",
92191
"- `nbdev_fix`\n",
@@ -99,47 +198,23 @@
99198
"id": "d12eaaae-04b1-41f9-a162-e8a4d7d3bef4",
100199
"metadata": {},
101200
"source": [
102-
"#### Pre-commit hooks: Automatically check notebooks before commits"
201+
"To configure your own hooks, Check out the [pre-commit hooks tutorial](/tutorials/pre_commit.ipynb)."
103202
]
104203
},
105204
{
106205
"cell_type": "markdown",
107-
"id": "a5992830-a000-4862-8eb8-d4856d7cdffd",
206+
"id": "7f6c261f-d47f-4d1a-a695-05370f81a9c9",
108207
"metadata": {},
109208
"source": [
110-
"Check out the [pre-commit hooks tutorial](/tutorials/pre_commit.ipynb) for more."
209+
"## Python Packaging"
111210
]
112211
},
113212
{
114213
"cell_type": "markdown",
115214
"id": "9b9a56e1",
116215
"metadata": {},
117216
"source": [
118-
"#### [`nbdev.release`](/api/release.html): Easy packaging on PyPI, conda, and GitHub"
119-
]
120-
},
121-
{
122-
"cell_type": "markdown",
123-
"id": "40810bf2",
124-
"metadata": {},
125-
"source": [
126-
"Check out the `nbdev.release` docs for more. Note that this functionality requires a settings.ini file."
127-
]
128-
},
129-
{
130-
"cell_type": "markdown",
131-
"id": "22d910d0",
132-
"metadata": {},
133-
"source": [
134-
"#### [`nbdev.quarto`](/api/quarto.html): Technical documentation with Quarto"
135-
]
136-
},
137-
{
138-
"cell_type": "markdown",
139-
"id": "368989e9",
140-
"metadata": {},
141-
"source": [
142-
"Check out the `nbdev.quarto` docs for more. Note that this functionality requires a settings.ini file."
217+
"`nbdev.release`provides utlities for easy packaging on PyPI, conda, and GitHub. Check out the [`nbdev.release`](/api/release.html) docs for more information. Note that this functionality requires a settings.ini file."
143218
]
144219
},
145220
{

0 commit comments

Comments
 (0)