added support for make html-noapi and html-quick for the docs build

docs/Makefile

@@ -10,6 +10,16 @@ html-noplot:
         echo "make html-noplot in $$i..."; \
         (cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) html-noplot); done
 
+html-noapi:
+	@for i in $(SUBDIRS); do \
+        echo "make html-noapi in $$i..."; \
+        (cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) html-noapi); done
+
+html-quick:
+	@for i in $(SUBDIRS); do \
+        echo "make html-quick in $$i..."; \
+        (cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) html-quick); done
+
 spelling:
 	@for i in $(SUBDIRS); do \
         echo "make spelling in $$i..."; \

docs/src/Makefile

@@ -49,7 +49,17 @@ html:
 html-noplot:
 	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
-	@echo "Build finished. The HTML (no gallery) pages are in $(BUILDDIR)/html"
+	@echo "Build finished. The HTML (no gallery docs) pages are in $(BUILDDIR)/html"
+
+html-noapi:
+	export SKIP_API=1; $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML (no api docs) pages are in $(BUILDDIR)/html"
+
+html-quick:
+	export SKIP_API=1; $(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML (no gallery or api docs) pages are in $(BUILDDIR)/html"
 
 spelling:
 	$(SPHINXBUILD) -b spelling $(SRCDIR) $(BUILDDIR)

docs/src/conf.py

@@ -35,8 +35,10 @@ def autolog(message):
     print("[{}] {}".format(ntpath.basename(__file__), message))
 
 
-# -- Are we running on the readthedocs server, if so do some setup -----------
+# -- Check for dev make options to build quicker
+skip_api = os.environ.get("SKIP_API")
 
+# -- Are we running on the readthedocs server, if so do some setup -----------
 on_rtd = os.environ.get("READTHEDOCS") == "True"
 
 if on_rtd:
@@ -156,11 +158,16 @@ def _dotv(version):
     "sphinx_gallery.gen_gallery",
     "matplotlib.sphinxext.mathmpl",
     "matplotlib.sphinxext.plot_directive",
-    # better api documentation (custom)
-    "custom_class_autodoc",
-    "custom_data_autodoc",
-    "generate_package_rst",
 ]
+
+if skip_api == "1":
+    autolog("Skipping the API docs generation (SKIP_API=1)")
+else:
+    # better api documentation (custom)
+    extensions.extend(
+        ["custom_class_autodoc", "custom_data_autodoc", "generate_package_rst"]
+    )
+
 # -- panels extension ---------------------------------------------------------
 # See https://sphinx-panels.readthedocs.io/en/latest/
 

docs/src/developers_guide/contributing_documentation.rst

@@ -36,13 +36,26 @@ When updating the documentation ensure the html build has *no errors* or
 Once the build is complete, if it is rerun it will only rebuild the impacted
 build artefacts so should take less time.
 
-There is also an option to perform a build but skip the
+There is an option to perform a build but skip the
 :ref:`contributing.documentation.gallery` creation completely.  This can be
 achieved via::
 
     make html-noplot
 
-If you wish to run a clean build you can run::
+Another option is to skip the :ref:`iris` documentation creation.  This can be
+useful as it reduces the time to build the documentation, however you may have
+some build warnings as there maybe references to the API documentation.
+This can be achieved via::
+
+    make html-noapi
+
+You can combine both the above and skip the
+:ref:`contributing.documentation.gallery` and :ref:`iris` documentation
+completely.  This can be achieved via::
+
+    make html-quick
+
+If you wish to run a full clean build you can run::
 
     make clean
     make html