Skip to content

Commit 07cd2a2

Browse files
alex-treebeardalex-treebeard
authored
Remove html report (#28)
1 parent 9d6aef7 commit 07cd2a2

14 files changed

+702
-937
lines changed

‎.github/workflows/pytest.yml

+2-3
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ jobs:
4242
extra_args: --verbose --all-files
4343

4444
- run: poetry run pytest tests/test_nb_run.py # run without extras
45-
- run: poetry install -E html
45+
- run: poetry install
4646
- run: poetry run pytest --cov-report=xml --cov=src
4747

4848
- run: poetry run python -m ipykernel install --user --name nbmake
@@ -88,12 +88,11 @@ jobs:
8888
pytest --nbmake teachopencadd/talktorials/T000_template/talktorial.ipynb \
8989
- shell: bash -l {0}
9090
run: |
91-
pip install './nbmake[html]'
91+
pip install './nbmake'
9292
- shell: bash -l {0}
9393
run: |
9494
pytest \
9595
--nbmake \
96-
--path-output=. \
9796
-n=auto \
9897
teachopencadd/talktorials/T000_template/talktorial.ipynb \
9998
teachopencadd/talktorials/T002_compound_adme/talktorial.ipynb \

‎CONTRIBUTING.MD

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
2+
## Developing
3+
4+
### Install local package
5+
```
6+
poetry install
7+
```
8+
9+
### Activate shell
10+
```
11+
poetry shell
12+
```
13+
14+
### Run static checks
15+
```
16+
pre-commit run --all-files
17+
pre-commit install
18+
```
19+
20+
### Run tests
21+
```
22+
pytest
23+
```

‎README.md

+44-17
Original file line numberDiff line numberDiff line change
@@ -23,39 +23,66 @@ pip install pytest nbmake
2323
pytest --nbmake **/*ipynb
2424
```
2525

26-
**See [docs](https://treebeardtech.github.io/nbmake) for more.**
27-
<br/>
28-
<br/>
26+
## Allow errors and Configure Cell Timeouts
2927

30-
## See Also
28+
nbmake is built on top of [nbclient](https://github.com/jupyter/nbclient) and designed to compatible with nbsphinx and jupyter-book.
3129

32-
* [nbmake-action](https://github.com/treebeardtech/nbmake-action)
30+
The [jupyter book docs](https://jupyterbook.org/content/execute.html?highlight=allow_error#dealing-with-code-that-raises-errors) have a good description of how to ignore errors -- note that nbmake does not work with the external `_config.yml` configuration file. You must use the notebook JSON metadata field.
3331

34-
### HTML Report Example
32+
## Parallelisation
3533

36-
![HTML Report](docs/screen.png)
34+
Parallelisation with xdist is experimental upon initial release, but you can try it out:
35+
```
36+
pip install pytest-xdist
37+
38+
pytest --nbmake -n=auto
39+
```
3740

41+
It is also possible to parallelise at a CI-level using strategies, see [example](https://github.com/LabForComputationalVision/plenoptic/blob/master/.github/workflows/treebeard.yml)
3842

39-
## Developing
43+
### Build Jupyter Books Faster
44+
45+
Using xdist and the `--overwrite` flag let you build a large jupyter book repo faster:
4046

41-
### Install local package
4247
```
43-
poetry install -E html
48+
pytest --nbmake --overwrite -n=auto examples
49+
jb build examples
4450
```
51+
## Advice on Usage
52+
53+
nbmake is best used in a scenario where you use the ipynb files only for development. Consumption of notebooks is primarily done via a docs site, built through jupyter book, nbsphinx, or some other means. If using one of these tools, you are able to write assertion code in cells which will be [hidden from readers](https://jupyterbook.org/interactive/hiding.html).
54+
55+
### Pre-commit
56+
57+
Treating notebooks like source files lets you keep your repo minimal. Some tools, such as plotly may drop several megabytes of javascript in your output cells, as a result, stripping out notebooks on pre-commit is advisable:
4558

46-
### Activate shell
4759
```
48-
poetry shell
60+
# .pre-commit-config.yaml
61+
repos:
62+
- repo: https://github.com/kynan/nbstripout
63+
rev: master
64+
hooks:
65+
- id: nbstripout
4966
```
5067

51-
### Run static checks
68+
See https://pre-commit.com/ for more...
69+
70+
## Disable Nbmake
71+
72+
Implicitly:
5273
```
53-
pre-commit run --all-files
54-
pre-commit install
74+
pytest
5575
```
5676

57-
### Run tests
77+
Explicitly:
5878
```
59-
pytest
79+
pytest -p no:nbmake
6080
```
6181

82+
## See Also:
83+
84+
* [nbmake action](https://github.com/treebeardtech/treebeard)
85+
* [pytest](https://pytest.org/)
86+
* [jupyter book](https://github.com/executablebooks/jupyter-book)
87+
* [jupyter cache](https://github.com/executablebooks/jupyter-cache)
88+
* [MyST-NB](https://github.com/executablebooks/MyST-NB)

‎docs/landing-page.ipynb

+2-227
Original file line numberDiff line numberDiff line change
@@ -11,234 +11,9 @@
1111
"cell_type": "markdown",
1212
"metadata": {},
1313
"source": [
14-
"nbmake tests notebook documentation and is designed for notebooks which are non-deterministic.\n",
14+
"See the README for details: \n",
1515
"\n",
16-
"Despite being a pytest plugin, nbmake is kernel agnostic. It supports any language."
17-
]
18-
},
19-
{
20-
"cell_type": "markdown",
21-
"metadata": {},
22-
"source": [
23-
"\n",
24-
"## Quickstart\n",
25-
"\n",
26-
"```bash\n",
27-
"pip install pytest nbmake\n",
28-
"pytest --nbmake\n",
29-
"```\n",
30-
"\n",
31-
"### Output\n",
32-
"```\n",
33-
"========================================================================================== test session starts ==========================================================================================\n",
34-
"platform darwin -- Python 3.7.6, pytest-6.1.2, py-1.9.0, pluggy-0.13.1\n",
35-
"rootdir: /Users/asdf/git/treebeardtech/nbmake, configfile: pytest.ini\n",
36-
"plugins: nbmake-0.0.1, xdist-2.1.0, cov-2.10.1, forked-1.3.0\n",
37-
"collected 1 item \n",
38-
"\n",
39-
"landing-page.ipynb . [100%]\n",
40-
"\n",
41-
"=========================================================================================== 1 passed in 1.56s ===========================================================================================\n",
42-
"\n",
43-
"```"
44-
]
45-
},
46-
{
47-
"cell_type": "markdown",
48-
"metadata": {},
49-
"source": [
50-
"## Command Line Options\n",
51-
"\n",
52-
"Using the following options you can control how notebooks are executed, and configure CI pipelines"
53-
]
54-
},
55-
{
56-
"cell_type": "code",
57-
"execution_count": null,
58-
"metadata": {
59-
"tags": [
60-
"hide-input"
61-
]
62-
},
63-
"outputs": [],
64-
"source": [
65-
"!pytest -h | grep -A6 'notebook testing'"
66-
]
67-
},
68-
{
69-
"cell_type": "markdown",
70-
"metadata": {},
71-
"source": [
72-
"## Run Only Against IPYNB Files\n",
73-
"\n",
74-
"```\n",
75-
"pytest --nbmake **/*ipynb\n",
76-
"```"
77-
]
78-
},
79-
{
80-
"cell_type": "markdown",
81-
"metadata": {},
82-
"source": [
83-
"## Create an HTML Report\n",
84-
"\n",
85-
"To view outputs executed remotely, install jupyter-book:\n",
86-
"```\n",
87-
"pip install pytest 'nbmake[html]'\n",
88-
"```\n",
89-
"\n",
90-
"Then specify a path:\n",
91-
"```\n",
92-
"pytest --nbmake --path-output=.\n",
93-
"```\n",
94-
"\n",
95-
"### Output\n",
96-
"```\n",
97-
"========================================================================================== test session starts ==========================================================================================\n",
98-
"platform darwin -- Python 3.7.6, pytest-6.1.2, py-1.9.0, pluggy-0.13.1\n",
99-
"rootdir: /Users/asdf/git/treebeardtech/nbmake, configfile: pytest.ini\n",
100-
"plugins: nbmake-0.0.1, xdist-2.1.0, cov-2.10.1, forked-1.3.0\n",
101-
"collected 1 item \n",
102-
"\n",
103-
"landing-page.ipynb . [100%]\n",
104-
"\n",
105-
"\n",
106-
"2020-12-11 11:10:48 nbmake building test report at: \n",
107-
"\n",
108-
" file:///Users/asdf/git/treebeardtech/nbmake/docs/_build/html/index.html\n",
109-
"\n",
110-
"2020-12-11 11:10:50 done.\n",
111-
"\n",
112-
"=========================================================================================== 1 passed in 4.26s ===========================================================================================\n",
113-
"```\n",
114-
"\n",
115-
"The report contains only the stripped out and executed notebooks\n",
116-
"![HTML report](screen.png)"
117-
]
118-
},
119-
{
120-
"cell_type": "markdown",
121-
"metadata": {},
122-
"source": [
123-
"## Run and upload report on GitHub Actions using Netlify\n",
124-
"\n",
125-
"```yaml\n",
126-
" - run: pip install pytest 'nbmake[html]'\n",
127-
" - run: |\n",
128-
" pytest --nbmake --path-output=.\n",
129-
" - if: failure()\n",
130-
" run: |\n",
131-
" netlify deploy --dir=_build/html --auth=${{ secrets.NETLIFY_TOKEN }} --site=${{ secrets.NETLIFY_SITE_API_ID }}\n",
132-
"```\n",
133-
"```\n",
134-
"...\n",
135-
"- Waiting for deploy to go live...\n",
136-
"✔ Deploy is live!\n",
137-
"\n",
138-
"Logs: https://app.netlify.com/sites/festive-payne-ce084c/deploys/5fcf58ec72dc52a440dffcd7\n",
139-
"Website Draft URL: https://5fcf58ec72dc52a440dffcd7--festive-payne-ce084c.netlify.app\n",
140-
"```\n",
141-
"\n",
142-
"Note you can also run the tests using [nbmake-action](https://github.com/treebeardtech/treebeard) for this."
143-
]
144-
},
145-
{
146-
"cell_type": "markdown",
147-
"metadata": {},
148-
"source": [
149-
"## Disable Nbmake\n",
150-
"\n",
151-
"Implicitly:\n",
152-
"```\n",
153-
"pytest\n",
154-
"```\n",
155-
"\n",
156-
"Explicitly:\n",
157-
"```\n",
158-
"pytest -p no:nbmake\n",
159-
"```"
160-
]
161-
},
162-
{
163-
"cell_type": "markdown",
164-
"metadata": {},
165-
"source": [
166-
"## Allow errors and Configure Cell Timeouts\n",
167-
"\n",
168-
"nbmake is designed to compatible with jupyter book config (placed in notebook `metadata`, not the global config.yml)\n",
169-
"\n",
170-
"See [jupyter book docs](https://jupyterbook.org/content/execute.html?highlight=allow_error#dealing-with-code-that-raises-errors)"
171-
]
172-
},
173-
{
174-
"cell_type": "markdown",
175-
"metadata": {},
176-
"source": [
177-
"## Parallelisation\n",
178-
"\n",
179-
"Parallelisation with xdist is experimental upon initial release, but you can try it out:\n",
180-
"```\n",
181-
"pip install pytest-xdist\n",
182-
"\n",
183-
"pytest --nbmake -n=auto\n",
184-
"```\n",
185-
"\n",
186-
"It is also possible to parallelise at a CI-level using strategies, see [example](https://github.com/LabForComputationalVision/plenoptic/blob/master/.github/workflows/treebeard.yml)\n",
187-
"\n",
188-
"### Build Jupyter Books Faster\n",
189-
"\n",
190-
"Using xdist and the `--overwrite` flag let you build a large jupyter book repo faster:\n",
191-
"\n",
192-
"```\n",
193-
"pytest --nbmake --overwrite -n=auto examples\n",
194-
"jb build examples\n",
195-
"```"
196-
]
197-
},
198-
{
199-
"cell_type": "markdown",
200-
"metadata": {},
201-
"source": [
202-
"## Advice on Usage\n",
203-
"\n",
204-
"nbmake is best used in a scenario where you use the ipynb files only for development. Consumption of notebooks is primarily done via a docs site, built through jupyter book, nbsphinx, or some other means. If using one of these tools, you are able to write assertion code in cells which will be [hidden from readers](https://jupyterbook.org/interactive/hiding.html).\n",
205-
"\n",
206-
"### Pre-commit\n",
207-
"\n",
208-
"Treating notebooks like source files lets you keep your repo minimal. Some tools, such as plotly may drop several megabytes of javascript in your output cells, as a result, stripping out notebooks on pre-commit is advisable:\n",
209-
"\n",
210-
"```\n",
211-
"# .pre-commit-config.yaml\n",
212-
"repos:\n",
213-
" - repo: https://github.com/kynan/nbstripout\n",
214-
" rev: master\n",
215-
" hooks:\n",
216-
" - id: nbstripout\n",
217-
"```\n",
218-
"\n",
219-
"See https://pre-commit.com/ for more..."
220-
]
221-
},
222-
{
223-
"cell_type": "markdown",
224-
"metadata": {},
225-
"source": [
226-
"## Contributing\n",
227-
"\n",
228-
"Feedback is the best contribution you can make as a user of this tool. Join the [Slack channel](https://join.slack.com/t/treebeard-entmoot/shared_invite/zt-jyvuqted-xBjnbvlfcu5P2ltBvn1~mg) and bug me (Alex), and raise an [issue](https://github.com/treebeardtech/nbmake/issues), even if you think you are the only person with this problem."
229-
]
230-
},
231-
{
232-
"cell_type": "markdown",
233-
"metadata": {},
234-
"source": [
235-
"## See Also:\n",
236-
"\n",
237-
"* [nbmake action](https://github.com/treebeardtech/treebeard)\n",
238-
"* [pytest](https://pytest.org/)\n",
239-
"* [jupyter book](https://github.com/executablebooks/jupyter-book)\n",
240-
"* [jupyter cache](https://github.com/executablebooks/jupyter-cache)\n",
241-
"* [MyST-NB](https://github.com/executablebooks/MyST-NB)\n"
16+
"https://github.com/treebeardtech/nbmake"
24217
]
24318
}
24419
],

‎docs/screen.png

-206 KB
Binary file not shown.

0 commit comments

Comments
 (0)