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

David Lehman dlehman at redhat.com
Fri Jul 18 13:03:20 UTC 2014


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
>



More information about the anaconda-patches mailing list