Skip to content

Commit d2bd8df

Browse files
Update RECIPES.md w/ practical guidance on building
1 parent 7997f61 commit d2bd8df

File tree

1 file changed

+20
-2
lines changed

1 file changed

+20
-2
lines changed

RECIPES.md

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,11 @@
1919
pip install sphinx==2.4.5
2020
```
2121

22+
* **Note** this is a very old very of Sphinx and some of its plugins etc., which will be updated soon so we
23+
use the latest, but is necessary for now to maintain certain features. When installing libraries, take
24+
care not to allow the newest version of Sphinx to be installed by default during the operation.
25+
26+
2227
## Notes
2328

2429
* The `.py` files to generate recipes are stored in `docs/source/recipes/`.
@@ -57,7 +62,20 @@
5762
<button data-filter="testfilter">Test</button>
5863
</div>
5964
```
60-
65+
66+
6167
## Building for a release
6268

63-
TODO
69+
* Since the datasets to use are often very large, it is best to build only new recipes and re-build any
70+
which have been updated (usually to replace deprecated keywords or methods, etc.).
71+
* To force the prevention of re-builds, move the relevant `docs/source/recipes/plot_*_recipe.py` script(s)
72+
out of that directory (or `rm` them, they can be recovered by version control) and they won't be built.
73+
Use that to build only recipes that are new or updated.
74+
* The HTML files, code and generated notebooks under `_downloads` and generated plots
75+
and thumbnail images under `_images`, for any previously-built recipes, can then be manually copied
76+
across from stored archive builds, to create the full recipe listing.
77+
* The `index.html` will need to be updated to list the previously-generated recipes, also.
78+
* Note that recipes built for the `dev` or `archive` documentation builds will have paths in the
79+
recipes HTML files beginning with the relative path `../../` whereas for the `latest` documentation
80+
build this needs to be `../` only i.e. is one level up in the tree structure, so if copying anything over
81+
note this might need to be updated.

0 commit comments

Comments
 (0)