[ovs-dev] [RFC] make: Add 'lint-docs' target

[Russell Bryant]

On Thu, Nov 12, 2015 at 9:18 PM, Stephen Finucane <
stephen.finucane at intel.com> wrote:

> This provides a quick, easy way to use the 'mdl' executable provided
> in markdowlinter to validate documentation.
>
> This change does not resolve any of the issues this linter raises -
> these will need to be done in a follow up patch.
>
> Signed-off-by: Stephen Finucane <stephen.finucane at intel.com>
> ---
>  INSTALL.md  | 5 +++++
>  Makefile.am | 4 ++++
>  2 files changed, 9 insertions(+)
>
> diff --git a/INSTALL.md b/INSTALL.md
> index 906825a..7311915 100644
> --- a/INSTALL.md
> +++ b/INSTALL.md
> @@ -111,6 +111,11 @@ To run the unit tests, you also need:
>    - Perl.  Version 5.10.1 is known to work.  Earlier versions should
>      also work.
>
> +If you are going to modify Open vSwitch documentation, please consider
> +installing the following to validate your changes:
> +
> +  - "markdownlint" (https://github.com/mivok/markdownlint)
> +
>  The ovs-vswitchd.conf.db(5) manpage will include an E-R diagram, in
>  formats other than plain text, only if you have the following:
>
> diff --git a/Makefile.am b/Makefile.am
> index 966ba27..d58cb59 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -377,6 +377,10 @@ dist-docs:
>         VERSION=$(VERSION) $(srcdir)/build-aux/dist-docs $(srcdir) $(docs)
>  .PHONY: dist-docs
>
> +lint-docs:
> +       mdl $(docs)
> +.PHONY: dist-docs


You have a typo here: s/dist-docs/lint-docs/

What results does this come up with for the current docs?  That'd probably
help demonstrate the value.  I got errors trying to install mdl and decided
to just ask for now instead.  :-)

In general though, I think this seems like a fine idea.

-- 
Russell Bryant