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

[Finucane, Stephen]

On 13 Nov 13:18, Russell Bryant wrote:
> On Fri, Nov 13, 2015 at 11:40 AM, Finucane, Stephen <
> stephen.finucane at intel.com> wrote:
> 
> > On 13 Nov 14:08, Russell Bryant wrote:
> > > 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/
> >
> > This is what happens when I write code at night :)
> >
> > > 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.
> >
> > Are you ready for this (starts humming the Space Jam tune)? I've dropped
> > roughly 60%
> > of the "issues" so I may be missing some error types, but you should get
> > the gist.
> > This is all configurable, so we can switch off what we don't agree with.
> > AFAIK the
> > tool supports custom rules also so we could add our own (locally or
> > upstream) for
> > commonly seen issues.
> >
> 
> Thanks for sharing.
> 
> It'd be nice to strip this down to errors that will actually negatively
> affect the docs getting rendered properly.  If it's something that breaks
> viewing the doc on github or breaks the HTML version in dist-docs, that's
> something that would be  nice to catch automatically.  I'm personally much
> less concerned about the style nits.

Yeah, I agree. There's some stuff in there that definitely doesn't need to be
there.

So the idea is good, but what about the actual tool? Are we happy to proceed
with this 'mdl' tool or should we use something else (or just build one, a la
OpenStack :)) If the former, I should note that the package is not available
on any distro yet: is linking to GitHub suitable?

Stephen