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

David Lehman dlehman at redhat.com
Fri Jul 18 13:57:25 UTC 2014


On 07/18/2014 08:42 AM, Anne Mulhern wrote:
>
>
>
>
> ----- 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.

Agreed.

>
> - mulhern
> _______________________________________________
> anaconda-patches mailing list
> anaconda-patches at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/anaconda-patches
>



More information about the anaconda-patches mailing list