Hi Remy, I like what this does, and it'll be helpful in ensuring we
don't have broken links. However, there are some issues.
On Tue, 14 Feb 2017, Remy Leone <remy.leone@xxxxxxxx> wrote:
> From: Rémy Léone <remy.leone@xxxxxxxxx>
This area here is for the commit message, describing what linkcheck
does, why you think it's a good idea, and that anyone running it should
be aware that it'll try to connect to all URLs referenced in the
documentation.
This also needs a line in 'make help' output, with the warning that
it'll connect.
> Signed-off-by: Rémy Léone <remy.leone@xxxxxxxxx>
> ---
> Documentation/Makefile.sphinx | 3 +++
> Documentation/conf.py | 2 +-
> Makefile | 2 +-
> 3 files changed, 5 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
> index 707c653..bfacb1b 100644
> --- a/Documentation/Makefile.sphinx
> +++ b/Documentation/Makefile.sphinx
> @@ -68,6 +68,9 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
> htmldocs:
> @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
>
> +linkcheck:
> + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
Documentation/DocBook/Makefile needs a no-op target for
linkcheck. Unfortunately, so does Documentation/media/Makefile. (Did you
not see the "make[2]: *** No rule to make target 'linkcheck'. Stop."
warnings?)
> +
> latexdocs:
> @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 1ac958c..324fa92 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -34,7 +34,7 @@ from load_config import loadConfig
> # Add any Sphinx extension module names here, as strings. They can be
> # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
> # ones.
> -extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain']
> +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'sphinx.builders.linkcheck']
This results in "WARNING: extension 'sphinx.builders.linkcheck' has no
setup() function; is it really a Sphinx extension module?"
I don't think you need to add builders to extensions at all, do you?
Seems to work just fine without.
>
> # The name of the math extension changed on Sphinx 1.4
> if major == 1 and minor > 3:
> diff --git a/Makefile b/Makefile
> index 96e2352..1f93b3c 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1444,7 +1444,7 @@ $(help-board-dirs): help-%:
>
> # Documentation targets
> # ---------------------------------------------------------------------------
> -DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs
> +DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs linkcheck
Historically the documentation targets were '%docs', i.e. anything with
the docs suffix. I thought it would be better to call out the targets
explicitly, but perhaps that's not the case if it encourages targets
without docs suffix. Otherwise we'll have to keep touching
no-dot-config-targets too, which is not desirable ('make linkcheck'
as-is runs the config target).
In short, I think this should be called linkcheckdocs.
BR,
Jani.
> PHONY += $(DOC_TARGETS)
> $(DOC_TARGETS): scripts_basic FORCE
> $(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype
--
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
