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

Finucane, Stephen stephen.finucane at intel.com
Fri Nov 20 21:33:22 UTC 2015


On 15 Nov 19:10, Russell Bryant wrote:

[snip]

> > > 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?
> >
> 
> I'm not that concerned as long as running the tool is optional like you
> have it in the RFC.  It's a bummer that it's not packaged and it wouldn't
> install cleanly for me on Fedora (though I honestly only tried for about 2
> minutes).  I haven't looked at alternatives and I certainly don't think we
> should write our own.  I'll take your word for it if you've looked around
> at what's out there and this looks best.  :-)  I'll try it again later ...
> 
> I'm curious what real errors this catches that we wouldn't already catch
> with just converting it to HTML.
> 
> -- 
> Russell Bryant

I don't think there's such a thing as a "real error" in Markdown - the output
is just not as expected [1]. This tool does, however, seem to catch some
obvious errors. For example, in the below we see what should be two lines of
text and a code block

Some text

  echo "Hello, world"

some more text

But because the code isn't indented with the correct number of spaces (4+),
this isn't detected as code. The DPDK doc [2], which I'm trying to rework at
the moment, is littered with these mistakes [3]. I'm thinking this tool will
catch error like code blocks not being indented enough or bullet points at
funny levels but that's probably as good as we can get. How's that sound?

Stephen

[1] http://openvswitch.org/pipermail/dev/2015-February/051234.html
[2] https://raw.githubusercontent.com/openvswitch/ovs/89108874d59364313f9e5e192ba8ca00a2771d93/INSTALL.DPDK.md
[3] https://github.com/openvswitch/ovs/blob/89108874d59364313f9e5e192ba8ca00a2771d93/INSTALL.DPDK.md#dpdk-vhost-cuse-vm-configuration-with-libvirt



More information about the dev mailing list