Skip to content

Commit 5f206f6

Browse files
sadielbartholomewsadielbartholomew
authored
Merge pull request #919 from sadielbartholomew/docs-infra-updates
Decouple recipes gallery from main docs build
2 parents 992f144 + 158dc4a commit 5f206f6

File tree

119 files changed

+18747
-114
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

119 files changed

+18747
-114
lines changed

‎docs/source/conf.py‎

Lines changed: 0 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@
1818
import sys
1919

2020
import cfdm
21-
from sphinx_gallery.sorting import FileNameSortKey
2221

2322
import cf
2423

@@ -103,11 +102,6 @@ def _get_date():
103102
"sphinxcontrib.spelling",
104103
]
105104

106-
CF_DOCS_MODE = os.environ.get("CF_DOCS_MODE", "none")
107-
108-
if CF_DOCS_MODE in ["dev-recipes", "dev-recipes-scrub", "latest", "archive"]:
109-
extensions.append("sphinx_gallery.gen_gallery")
110-
111105
# Spelling extension configuration: set British English and false positives
112106
spelling_lang = "en_GB"
113107
tokenizer_lang = "en_GB"
@@ -382,26 +376,6 @@ def _get_date():
382376
# Output file base name for HTML help builder.
383377
htmlhelp_basename = "cfdoc"
384378

385-
# sphinx-gallery configuration
386-
sphinx_gallery_conf = {
387-
"examples_dirs": "recipes", # path to recipe files
388-
"gallery_dirs": "recipes", # path to save gallery generated output
389-
"run_stale_examples": False,
390-
# Below setting can be buggy: see:
391-
# https://github.com/sphinx-gallery/sphinx-gallery/issues/967
392-
# "reference_url": {"cf": None},
393-
"backreferences_dir": "gen_modules/backreferences",
394-
"doc_module": ("cf",),
395-
"inspect_global_variables": True,
396-
"within_subsection_order": FileNameSortKey,
397-
"default_thumb_file": "_static/cf-recipe-placeholder-squarecrop.png",
398-
"image_scrapers": (
399-
"matplotlib",
400-
), # Ensures Matplotlib images are captured
401-
"plot_gallery": True, # Enables plot rendering
402-
"reset_modules": ("matplotlib",), # Helps with memory management
403-
"capture_repr": (),
404-
}
405379

406380
import warnings
407381

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,5 +22,5 @@ line_length=79
2222
# which can cause a seg fault if cf-plot/matplotlib is imported first.
2323
extend_skip_glob = [
2424
"**/__init__.py",
25-
"docs/source/recipes/**",
25+
"recipes-docs/source/recipes/**",
2626
]

‎recipes-docs/Makefile‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS = -j 1
6+
SPHINXBUILD = sphinx-build
7+
PAPER =
8+
#BUILDDIR = build
9+
10+
# Internal variables.
11+
PAPEROPT_a4 = -D latex_paper_size=a4
12+
PAPEROPT_letter = -D latex_paper_size=letter
13+
#ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
14+
ALLSPHINXOPTS = $(SPHINXOPTS) source
15+
BUILDDIR = $(filter-out $@, $(MAKECMDGOALS))
16+
17+
18+
.PHONY: help clean html spelling dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
19+
20+
help:
21+
@echo "Please use \`make <target>' where <target> is one of"
22+
@echo " html to make standalone HTML files"
23+
@echo " dirhtml to make HTML files named index.html in directories"
24+
@echo " singlehtml to make a single large HTML file"
25+
@echo " pickle to make pickle files"
26+
@echo " json to make JSON files"
27+
@echo " htmlhelp to make HTML files and a HTML help project"
28+
@echo " qthelp to make HTML files and a qthelp project"
29+
@echo " devhelp to make HTML files and a Devhelp project"
30+
@echo " epub to make an epub"
31+
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
32+
@echo " latexpdf to make LaTeX files and run them through pdflatex"
33+
@echo " text to make text files"
34+
@echo " man to make manual pages"
35+
@echo " changes to make an overview of all changed/added/deprecated items"
36+
@echo " linkcheck to check all external links for integrity"
37+
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
38+
39+
clean:
40+
$(if $(BUILDDIR),,$(error BUILDDIR to clean must be defined))
41+
-rm -rf $(BUILDDIR)/*
42+
43+
html:
44+
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)
45+
@echo
46+
@echo "Build finished. The HTML pages are in $(BUILDDIR)"
47+
48+
spelling:
49+
$(SPHINXBUILD) -b spelling $(ALLSPHINXOPTS) $(BUILDDIR)/spelling
50+
@echo
51+
@echo "Spelling check dummy finished. Results are in $(BUILDDIR)/spelling."
52+
53+
dirhtml:
54+
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
55+
@echo
56+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
57+
58+
singlehtml:
59+
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
60+
@echo
61+
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
62+
63+
pickle:
64+
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
65+
@echo
66+
@echo "Build finished; now you can process the pickle files."
67+
68+
json:
69+
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
70+
@echo
71+
@echo "Build finished; now you can process the JSON files."
72+
73+
htmlhelp:
74+
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
75+
@echo
76+
@echo "Build finished; now you can run HTML Help Workshop with the" \
77+
".hhp project file in $(BUILDDIR)/htmlhelp."
78+
79+
qthelp:
80+
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
81+
@echo
82+
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
83+
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
84+
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/y.qhcp"
85+
@echo "To view the help file:"
86+
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/y.qhc"
87+
88+
devhelp:
89+
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
90+
@echo
91+
@echo "Build finished."
92+
@echo "To view the help file:"
93+
@echo "# mkdir -p $$HOME/.local/share/devhelp/y"
94+
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/y"
95+
@echo "# devhelp"
96+
97+
epub:
98+
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
99+
@echo
100+
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
101+
102+
latex:
103+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
104+
@echo
105+
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
106+
@echo "Run \`make' in that directory to run these through (pdf)latex" \
107+
"(use \`make latexpdf' here to do that automatically)."
108+
109+
latexpdf:
110+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
111+
@echo "Running LaTeX files through pdflatex..."
112+
make -C $(BUILDDIR)/latex all-pdf
113+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
114+
115+
text:
116+
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
117+
@echo
118+
@echo "Build finished. The text files are in $(BUILDDIR)/text."
119+
120+
man:
121+
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
122+
@echo
123+
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
124+
125+
changes:
126+
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
127+
@echo
128+
@echo "The overview file is in $(BUILDDIR)/changes."
129+
130+
linkcheck:
131+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
132+
@echo
133+
@echo "Link check complete; look for any errors in the above output " \
134+
"or in $(BUILDDIR)/linkcheck/output.txt."
135+
136+
doctest:
137+
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
138+
@echo "Testing of doctests in the sources finished, look at the " \
139+
"results in $(BUILDDIR)/doctest/output.txt."

‎recipes-docs/source/conf.py‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import os
2+
import sys
3+
4+
from sphinx_gallery.sorting import FileNameSortKey
5+
6+
# Make main 'docs' conf.py importable
7+
sys.path.insert(0, os.path.abspath("../../docs/source"))
8+
9+
# Import everything from the main docs configuration
10+
from conf import * # noqa: F403
11+
12+
# Now update the main docs configuration for recipes-specific needs
13+
# TODO
14+
# CF_DOCS_MODE = os.environ.get("CF_DOCS_MODE", "none")
15+
# if CF_DOCS_MODE in ["dev-recipes", "dev-recipes-scrub", "latest", "archive"]:
16+
17+
# We need to use and configure sphinx-gallery for the recipes
18+
extensions.append("sphinx_gallery.gen_gallery") # noqa: F405
19+
20+
# sphinx-gallery configuration
21+
sphinx_gallery_conf = {
22+
"examples_dirs": "recipes", # path to recipe files
23+
"gallery_dirs": "recipes", # path to save gallery generated output
24+
"run_stale_examples": False,
25+
# Below setting can be buggy: see:
26+
# https://github.com/sphinx-gallery/sphinx-gallery/issues/967
27+
# "reference_url": {"cf": None},
28+
"backreferences_dir": "gen_modules/backreferences",
29+
"doc_module": ("cf",),
30+
"inspect_global_variables": True,
31+
"within_subsection_order": FileNameSortKey,
32+
"default_thumb_file": "_static/cf-recipe-placeholder-squarecrop.png",
33+
"image_scrapers": (
34+
"matplotlib",
35+
), # Ensures Matplotlib images are captured
36+
"plot_gallery": True, # Enables plot rendering
37+
"reset_modules": ("matplotlib",), # Helps with memory management
38+
"capture_repr": (),
39+
}
40+
41+
html_static_path = ["../../docs/source/_static"]
42+
html_logo = "../../docs/source/images/logo.svg"
43+
html_favicon = "../../docs/source/_static/favicon.ico"

‎recipes-docs/source/index.rst‎

Lines changed: 95 additions & 0 deletions

docs/source/recipes/README.rst renamed to recipes-docs/source/recipes/README.rst

‎recipes-docs/source/recipes/cfplot.png‎

166 KB

‎recipes-docs/source/recipes/global_avg_sst_plot.png‎

320 KB

docs/source/recipes/images/GALLERY_HEADER.rst renamed to recipes-docs/source/recipes/images/GALLERY_HEADER.rst

‎recipes-docs/source/recipes/images/index.rst‎

Lines changed: 22 additions & 0 deletions

0 commit comments

Comments
 (0)