diff --git a/docs/Makefile b/docs/Makefile index e9632ddb9f..44c89206d2 100644 --- a/docs/Makefile +++ b/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..."; \ diff --git a/docs/src/Makefile b/docs/src/Makefile index 2e47057a30..c693a2c900 100644 --- a/docs/src/Makefile +++ b/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) diff --git a/docs/src/conf.py b/docs/src/conf.py index 1c7cc7c3f2..e13f12a13a 100644 --- a/docs/src/conf.py +++ b/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/ diff --git a/docs/src/developers_guide/contributing_documentation.rst b/docs/src/developers_guide/contributing_documentation.rst index 19b9761b8f..efd31d4f20 100644 --- a/docs/src/developers_guide/contributing_documentation.rst +++ b/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 diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index 34c1c56fe7..d06a0c2803 100644 --- a/docs/src/whatsnew/latest.rst +++ b/docs/src/whatsnew/latest.rst @@ -111,6 +111,10 @@ This document explains the changes made to Iris for this release #. `@wjbenfold`_ excluded "Good First Issue" labelled issues from being marked stale. (:pull:`4317`) +#. `@tkknight`_ added additional make targets for reducing the time of the + documentation build including ``html-noapi`` and ``html-quick``. + Useful for development purposes only. For more information see + :ref:`contributing.documentation.building` the documentation. (:pull:`4333`) .. comment Whatsnew author names (@github name) in alphabetical order. Note that,