On Fri, Nov 13, 2015 at 6:03 PM, Finucane, Stephen < stephen.finuc...@intel.com> wrote:
> On 13 Nov 13:18, Russell Bryant wrote: > > On Fri, Nov 13, 2015 at 11:40 AM, Finucane, Stephen < > > stephen.finuc...@intel.com> wrote: > > > > > On 13 Nov 14:08, Russell Bryant wrote: > > > > On Thu, Nov 12, 2015 at 9:18 PM, Stephen Finucane < > > > stephen.finuc...@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.finuc...@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? > 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 _______________________________________________ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
