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

Anne Mulhern amulhern at redhat.com
Fri Jul 18 13:42:38 UTC 2014





----- Original Message -----
> From: "David Lehman" <dlehman at redhat.com>
> To: anaconda-patches at lists.fedorahosted.org
> Sent: Friday, July 18, 2014 9:03:20 AM
> Subject: Re: [PATCH] Mock non-standard modules so we can generate API docs	on readthedocs.
> 
> On 07/18/2014 07:51 AM, Anne Mulhern wrote:
> >
> >
> >
> >
> > ----- 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.
> 
> I considered doing so. I'll add a link in a comment.
> 
> >
> > 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.
> 
> None of the mocked projects are documented using sphinx AFAIK so I don't
> expect this change to decrease the quality of the blivet docs. If they
> had readliy available sphinx docs I would certainly prefer to link to it.
> 
> David
> 
> >
> > - mulhern
> >
> >
> > _______________________________________________
> > anaconda-patches mailing list
> > anaconda-patches at lists.fedorahosted.org
> > https://lists.fedorahosted.org/mailman/listinfo/anaconda-patches
> >
> 
> _______________________________________________
> anaconda-patches mailing list
> anaconda-patches at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/anaconda-patches
> 

The most interesting diff I noted is that, w/out patch we get, e.g.

partedFlag = 12

whereas with patch

partedFlag
  alias of PARTITION_BIOS_GRUB

which is better anyway, IMHO.

Best would be,

partedFlag = parted.PARTITION_BIOS_GRUB

which we don't get either way.

- mulhern


More information about the anaconda-patches mailing list