[blivet:master 3/5] Add doctest extension so that doctest target runs.

Anne Mulhern amulhern at redhat.com
Fri Jun 13 12:38:22 UTC 2014





----- Original Message -----
> From: "Brian C. Lane" <bcl at redhat.com>
> To: anaconda-patches at lists.fedorahosted.org
> Sent: Wednesday, June 11, 2014 8:51:15 PM
> Subject: Re: [blivet:master 3/5] Add doctest extension so that doctest target	runs.
> 
> On Tue, Jun 10, 2014 at 05:17:02PM -0400, mulhern wrote:
> > Currently, the blivet docs contain no doctest material, so the target
> > does nothing.
> > 
> > Signed-off-by: mulhern <amulhern at redhat.com>
> > ---
> >  doc/conf.py | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/doc/conf.py b/doc/conf.py
> > index ee696f2..eab3168 100644
> > --- a/doc/conf.py
> > +++ b/doc/conf.py
> > @@ -25,7 +25,7 @@ sys.path.insert(0, os.path.abspath('..'))
> >  
> >  # Add any Sphinx extension module names here, as strings. They can be
> >  extensions
> >  # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
> > -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx',
> > 'sphinx.ext.todo', 'sphinx.ext.coverage']
> > +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx',
> > 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.doctest']
> >  
> >  # Add any paths that contain templates here, relative to this directory.
> >  templates_path = ['_templates']
> > --
> > 1.9.3
> 
> Do we really want to support doctests? IMO they clutter up docstrings
> and make them harder to read.
> 
> --
> Brian C. Lane | Anaconda Team | IRC: bcl #anaconda | Port Orchard, WA
> (PST8PDT)
> _______________________________________________
> anaconda-patches mailing list
> anaconda-patches at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/anaconda-patches
> 

Well, there are a couple of reasons why we might not want to.

So far, we haven't used them anywhere in the code base.

Also, getting them to work in a real application with some kind of module
system is harder than they make it look in the examples, at least that's
my (very brief) experience so far.

And they may not be so useful for the kinds of things we actually want
to express in the documentation.

In sum, could be a lot of work to get any we actually might add to function
properly, with very little benefit.

I'ld be just as happy to change this patch to one that simply removes
the doctest target from the Makefile.

Let me know what you think.

Thanks!

- mulhern


More information about the anaconda-patches mailing list