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

Anne Mulhern amulhern at redhat.com
Fri Jul 18 12:51:16 UTC 2014





----- Original Message -----
> From: "Anne Mulhern" <amulhern at redhat.com>
> To: "anaconda patch review" <anaconda-patches at lists.fedorahosted.org>
> Sent: Friday, July 18, 2014 8:41:29 AM
> Subject: Re: [PATCH] Mock non-standard modules so we can generate API docs	on readthedocs.
> 
> 
> 
> 
> 
> ----- 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
> 
> 
> _______________________________________________
> anaconda-patches mailing list
> anaconda-patches at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/anaconda-patches
> 

Huh, I see that code is an exact copy of readthedocs' suggestion.
Do you understand that little chunk that so puzzled me?
Maybe the Mock class should contain a pointer to its readthedocs
source and maybe someday RTD will explain it.

Also, I notice that we can modify behavior depending on whether
RTD is generating the docs or we are, but at this point since
as far as I can tell the differences seem to be small and mostly
an improvement there really seems to be no point.

- mulhern




More information about the anaconda-patches mailing list