simplify doc/Makefile (JuliaLang#27145)

* simplify doc/Makefile

* move deploy target back to after_success
and make sure to only deploy once, fix JuliaLang#27292

.travis.yml

@@ -152,7 +152,11 @@ script:
  # restore initial state and prepare for travis caching
  - mv julia2 julia &&
  rm -f julia/deps/scratch/libgit2-*/CMakeFiles/CMakeOutput.log
+ # run the doctests on Linux 64-bit
+ - if [ `uname` = "Linux" ] && [ $ARCH = "x86_64" ]; then
+ pushd julia && make -C doc doctest=true && popd; fi
 # uncomment the following if failures are suspected to be due to the out-of-memory killer
 # - dmesg
- # build the docs and run the doctests
- - cd julia && make -C doc deploy
+-after_success:
+ - if [ `uname` = "Linux" ] && [ $ARCH = "x86_64" ]; then
+ cd julia && make -C doc deploy; fi

CONTRIBUTING.md

@@ -178,7 +178,7 @@ Examples written within docstrings can be used as testcases known as "doctests"
  "DOCSTRING TEST"
  ```
 
-A doctest needs to match an interactive REPL including the `julia>` prompt. To run doctests you need to run `make -C doc check` from the root directory. It is recommended to add the header `# Examples` above the doctests.
+A doctest needs to match an interactive REPL including the `julia>` prompt. To run doctests you need to run `make -C doc doctest=true` from the root directory. It is recommended to add the header `# Examples` above the doctests.
 
 #### News-worthy changes
 

Makefile

@@ -98,9 +98,8 @@ release-candidate: release testall
  @$(JULIA_EXECUTABLE) $(JULIAHOME)/contrib/add_license_to_files.jl #add license headers
  @#Check documentation
  @$(JULIA_EXECUTABLE) $(JULIAHOME)/doc/NEWS-update.jl #Add missing cross-references to NEWS.md
- @$(MAKE) -C $(BUILDROOT)/doc html
+ @$(MAKE) -C $(BUILDROOT)/doc html doctest=true linkcheck=true
  @$(MAKE) -C $(BUILDROOT)/doc pdf
- @$(MAKE) -C $(BUILDROOT)/doc check
 
  @# Check to see if the above make invocations changed anything important
  @if [ -n "$$(git status --porcelain)" ]; then \

doc/Makefile

@@ -8,16 +8,19 @@ JULIAHOME := $(abspath $(SRCDIR)/..)
 include $(JULIAHOME)/Make.inc
 JULIA_EXECUTABLE := $(call spawn,$(build_bindir)/julia)
 
-.PHONY: help clean cleanall html pdf linkcheck doctest doctest-fix check deps deploy
+.PHONY: help clean cleanall html pdf deps deploy
 
 help:
  @echo "Please use 'make <target>' where <target> is one of"
- @echo " html to make standalone HTML files"
- @echo " pdf to make standalone PDF file"
- @echo " linkcheck to check all external links for integrity"
- @echo " doctest to run all doctests embedded in the documentation"
- @echo " doctest-fix to update all doctests embedded in the documentation"
- @echo " check to run linkcheck and doctests"
+ @echo " html to make standalone HTML files"
+ @echo " pdf to make standalone PDF file"
+ @echo
+ @echo "To run linkcheck, use 'make <target> linkcheck=true'"
+ @echo "To run doctests, use 'make <target> doctest=true'"
+ @echo "To fix outdated doctests, use 'make <target> doctest=fix'"
+
+
+DOCUMENTER_OPTIONS := linkcheck=$(linkcheck) doctest=$(doctest)
 
 UnicodeData.txt:
  $(JLDOWNLOAD) http:https://www.unicode.org/Public/9.0.0/ucd/UnicodeData.txt
@@ -33,41 +36,21 @@ cleanall: clean
 html: deps
  @echo "Building HTML documentation."
 ifneq ($(OS),WINNT)
- $(JULIA_EXECUTABLE) --color=yes $(call cygpath_w,$(SRCDIR)/make.jl)
+ $(JULIA_EXECUTABLE) --color=yes $(call cygpath_w,$(SRCDIR)/make.jl) $(DOCUMENTER_OPTIONS)
 else
 # work around issue #11727, windows output redirection breaking on buildbot
- $(JULIA_EXECUTABLE) --color=yes $(call cygpath_w,$(SRCDIR)/make.jl) > docbuild.log 2>&1
+ $(JULIA_EXECUTABLE) --color=yes $(call cygpath_w,$(SRCDIR)/make.jl) $(DOCUMENTER_OPTIONS) > docbuild.log 2>&1
  @cat docbuild.log
 endif
  @echo "Build finished. The HTML pages are in _build/html."
 
 pdf: deps
  @echo "Building PDF documentation."
- $(JULIA_EXECUTABLE) --color=yes $(call cygpath_w,$(SRCDIR)/make.jl) -- pdf
+ $(JULIA_EXECUTABLE) --color=yes $(call cygpath_w,$(SRCDIR)/make.jl) -- pdf $(DOCUMENTER_OPTIONS)
  @echo "Build finished."
 
-linkcheck: deps
- @echo "Checking external documentation links."
- $(JULIA_EXECUTABLE) --color=yes $(call cygpath_w,$(SRCDIR)/make.jl) -- linkcheck
- @echo "Checks finished."
-
-doctest: deps
- @echo "Running all embedded 'doctests'."
- $(JULIA_EXECUTABLE) --color=yes $(call cygpath_w,$(SRCDIR)/make.jl) -- doctest
- @echo "Checks finished."
-
-doctest-fix: deps
- @echo "Updating all embedded 'doctests'."
- $(JULIA_EXECUTABLE) --color=yes $(call cygpath_w,$(SRCDIR)/make.jl) -- doctest-fix
- @echo "Update finished."
-
-check: deps
- @echo "Running all embedded 'doctests' and checking external links."
- $(JULIA_EXECUTABLE) --color=yes $(call cygpath_w,$(SRCDIR)/make.jl) -- doctest linkcheck
- @echo "Checks finished."
-
 # The deploy target should only be called in Travis builds
 deploy: deps
  @echo "Deploying HTML documentation."
- $(JULIA_EXECUTABLE) --color=yes $(call cygpath_w,$(SRCDIR)/make.jl) -- deploy doctest
+ $(JULIA_EXECUTABLE) --color=yes $(call cygpath_w,$(SRCDIR)/make.jl) -- deploy $(DOCUMENTER_OPTIONS)
  @echo "Build & deploy of docs finished."

doc/make.jl

@@ -1,9 +1,3 @@
-if "deploy" in ARGS
- # Only deploy docs from 64bit Linux to avoid committing multiple versions of the same
- # docs from different workers.
- (Sys.ARCH === :x86_64 && Sys.KERNEL === :Linux) || exit()
-end
-
 # Install dependencies needed to build the documentation.
 using Pkg
 empty!(DEPOT_PATH)
@@ -154,8 +148,8 @@ makedocs(
  build = joinpath(@__DIR__, "_build/html/en"),
  modules = [Base, Core, BuildSysImg, [Base.root_module(Base, stdlib.stdlib) for stdlib in STDLIB_DOCS]...],
  clean = true,
- doctest = ("doctest-fix" in ARGS) ? (:fix) : ("doctest" in ARGS),
- linkcheck = "linkcheck" in ARGS,
+ doctest = ("doctest=fix" in ARGS) ? (:fix) : ("doctest=true" in ARGS) ? true : false,
+ linkcheck = "linkcheck=true" in ARGS,
  linkcheck_ignore = ["https://bugs.kde.org/show_bug.cgi?id=136779"], # fails to load from nanosoldier?
  strict = true,
  checkdocs = :none,
@@ -169,16 +163,19 @@ makedocs(
  assets = ["assets/julia-manual.css", ]
 )
 
+# Only deploy docs from 64bit Linux to avoid committing multiple versions of the same
+# docs from different workers.
+if "deploy" in ARGS && Sys.ARCH === :x86_64 && Sys.KERNEL === :Linux
+ # Since the `.travis.yml` config specifies `language: cpp` and not `language: julia` we
+ # need to manually set the version of Julia that we are deploying the docs from.
+ ENV["TRAVIS_JULIA_VERSION"] = "nightly"
 
-# Since the `.travis.yml` config specifies `language: cpp` and not `language: julia` we
-# need to manually set the version of Julia that we are deploying the docs from.
-ENV["TRAVIS_JULIA_VERSION"] = "nightly"
-
-deploydocs(
- julia = "nightly",
- repo = "github.com/JuliaLang/julia.git",
- target = "_build/html/en",
- dirname = "en",
- deps = nothing,
- make = nothing,
-)
+ deploydocs(
+ julia = "nightly",
+ repo = "github.com/JuliaLang/julia.git",
+ target = "_build/html/en",
+ dirname = "en",
+ deps = nothing,
+ make = nothing,
+ )
+end