[PATCH] Mock non-standard modules so we can generate API docs on readthedocs.

Anne Mulhern amulhern at redhat.com
Fri Jul 18 12:41:29 UTC 2014





----- Original Message -----
> From: "Vratislav Podzimek" <vpodzime at redhat.com>
> To: "anaconda patch review" <anaconda-patches at lists.fedorahosted.org>
> Sent: Friday, July 18, 2014 1:21:56 AM
> Subject: Re: [PATCH] Mock non-standard modules so we can generate API docs	on readthedocs.
> 
> On Thu, 2014-07-17 at 15:44 -0500, David Lehman wrote:
> > ---
> >  doc/conf.py | 29 +++++++++++++++++++++++++++++
> >  1 file changed, 29 insertions(+)
> > 
> > diff --git a/doc/conf.py b/doc/conf.py
> > index 4b16a97..05594fd 100644
> > --- a/doc/conf.py
> > +++ b/doc/conf.py
> > @@ -289,3 +289,32 @@ epub_copyright = u'2013, David Lehman'
> >  
> >  # Example configuration for intersphinx: refer to the Python standard
> >  library.
> >  intersphinx_mapping = {'https://docs.python.org/2': None}
> > +
> > +class Mock(object):
> > +
> > +    __all__ = []
> > +
> > +    def __init__(self, *args, **kwargs):
> > +        pass
> > +
> > +    def __call__(self, *args, **kwargs):
> > +        return Mock()
> > +
> > +    @classmethod
> > +    def __getattr__(cls, name):
> > +        if name in ('__file__', '__path__'):
> > +            return '/dev/null'

The block below confuses me. It would probably help if there
were a comment that explained:

1. What special class of names are being identified by the condition.
2. Why only the first letter is being uppercased and checked
3. What is the expected value of __name__ in this context
and why setting it is important.
4. Why a class instead of an object of that class is being returned

> > +        elif name[0] == name[0].upper():
> > +            mockType = type(name, (), {})
> > +            mockType.__module__ = __name__
> > +            return mockType
> > +        else:
> > +            return Mock()
> > +
> > +    @classmethod
> > +    def __getitem__(cls, key):
> > +	return cls.__getattr__(key)
> > +
> > +MOCK_MODULES = ['parted', 'block', 'pycryptsetup', 'pykickstart',
> > 'pykickstart.constants', '_ped']
> > +for mod_name in MOCK_MODULES:
> > +    sys.modules[mod_name] = Mock()
> Interesting, but looks good to me as well.
> 
> --
> Vratislav Podzimek
> 
> Anaconda Rider | Red Hat, Inc. | Brno - Czech Republic
> 
> _______________________________________________
> anaconda-patches mailing list
> anaconda-patches at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/anaconda-patches
> 

Other suggestions are:

*. Expand the commit message to explain why this is an issue for readthedocs,
since it is not an issue for generating the documentation in situ.
*. Set up those hooks on readthedocs so that the new documentation is
generated w/ every commit, so that we can notice rapidly if anything
is going wrong.
* If there is any really interesting difference between the two versions
of the doc's, with and without the mock objects, mention it in commit
message. I looked at
the differences, and the version with the patch actually looks a bit better,
mostly with the way it documents parted* objects in blivet.formats.html.

- mulhern




More information about the anaconda-patches mailing list