[ovs-dev] [PATCH] Documentation: Report errors for use of features not in Sphinx 1.1.3.

Stephen Finucane stephen at that.guru
Wed Mar 8 09:15:07 UTC 2017


On Tue, 2017-03-07 at 10:54 -0800, Ben Pfaff wrote:
> Signed-off-by: Ben Pfaff <blp at ovn.org>

I'm not sure if this is completely necessary, but I imagine it won't
slow the build down too much and looks about right so:

Acked-by: Stephen Finucane <stephen at that.guru>

I'd also like to see a TODO describing the path to removing support for
Sphinx 1.1 (which is pretty old now) but what that path looks like, I
don't know.

Some other small points below.

> ---
>  Documentation/automake.mk              | 15 ++++++++++++++-
>  Documentation/sphinx-version-blacklist |  2 ++
>  2 files changed, 16 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/sphinx-version-blacklist
> 
> diff --git a/Documentation/automake.mk b/Documentation/automake.mk
> index a74807fde532..f7f1fe61d1b7 100644
> --- a/Documentation/automake.mk
> +++ b/Documentation/automake.mk
> @@ -86,7 +86,8 @@ EXTRA_DIST += \
>  	Documentation/internals/contributing/documentation-style.rst 
> \
>  	Documentation/internals/contributing/libopenvswitch-abi.rst
> \
>  	Documentation/internals/contributing/submitting-patches.rst
> \
> -	Documentation/requirements.txt
> +	Documentation/requirements.txt \
> +	Documentation/sphinx-version-blacklist

This still won't build locally for me so I can't validate it. Could you
just make sure this doesn't cause a failed doc build due to a warning
about documents that are not included in any table of contents. I think
only 'rst' files are included in that check, but I can't be sure.

>  
>  # You can set these variables from the command line.
>  SPHINXOPTS =
> @@ -120,3 +121,15 @@ endif
>  .PHONY: htmldocs
>  .PHONY: check-docs
>  .PHONY: clean-docs
> +
> +ALL_LOCAL += sphinx-version-check
> +sphinx-version-check: $(EXTRA_DIST)
> +	@if grep -n -f $(srcdir)/Documentation/sphinx-version-
> blacklist $?; \
> +	then \
> +	  echo "See above for list of uses of features that Sphinx
> 1.1.3"; \

Assuming Sphinx do semantic versioning correctly (they do), we can
simply say Sphinx 1.1 here.

> +	  echo "does not support.  Please avoid using these
> features.."; \
> +	  exit 1; \
> +	else \
> +          : > $@; \
> +	fi
> +CLEANFILES += sphinx-version-check
> diff --git a/Documentation/sphinx-version-blacklist
> b/Documentation/sphinx-version-blacklist
> new file mode 100644
> index 000000000000..a67339bf2758
> --- /dev/null
> +++ b/Documentation/sphinx-version-blacklist
> @@ -0,0 +1,2 @@
> +code-block:: *ps1con
> +code-block:: *doscon



More information about the dev mailing list