[SciPy-dev] maxentropy docs / parent class methods

[Skipper Seabold]

On Wed, Feb 17, 2010 at 6:16 AM, Ralf Gommers
<ralf.gommers@googlemail.com> wrote:
>
>
> On Wed, Feb 17, 2010 at 6:05 AM, Skipper Seabold <jsseabold@gmail.com>
> wrote:
>>
>> On Tue, Feb 16, 2010 at 4:41 PM,  <josef.pktd@gmail.com> wrote:
>> > On Tue, Feb 16, 2010 at 4:10 PM, Skipper Seabold <jsseabold@gmail.com>
>> > wrote:
>> >> The docs on the methods for the maxentropy model class that are
>> >> inherited from basemodel are not picked up by sphinx.  It seems that
>> >> most of the .rst files explicitly list the methods, but since
>> >> basemodel is not intended to be public (and some subclasses overwrite
>> >> the parent class methods), is there a better way than to start listing
>> >> the basemodel methods?
>> >>
>> >> I started to make the changes, but I don't think this is the right way
>> >> forward.  Other thoughts?
>> >>
>> >> http://docs.scipy.org/scipy/docs/scipy-docs/maxentropy.rst/
>> >
>> > Try to reference directly the basemodel.xxx method in the autoclass for
>> > model
>> >
>> > .. autoclass:: model
>> >
>> > .. autosummary::
>> >   :toctree: generated/
>> >
>> > .....
>> >   model.dual
>> >   basemodel.fit
>> >   model.grad
>> >   model.log
>> >
>> > Otherwise, it's better to have too much than too little information in
>> > the docs
>> >
>>
>> That works, but it's still the basemodel namespace under model.  I was
>> looking to statsmodels to see how we autogenerate the inherited
>> methods.  I might play around with a local build so I don't clutter up
>> the logs on the wiki.  It's changed so that they show up for now while
>> I clean up a little more but is probably not a final solution.
>>
> Those methods do not belong just to 'model' but also to 'bigmodel' and
> 'conditionalmodel'. So listing them under 'model' is a bit arbitrary. I
> think the correct way to do this is to list them under an .. autoclass::
> basemodel, with a note that this class contains shared functionality and
> should not be instantiated directly.
>

Agreed.  I will try this and make sure the note that is already in the
docstring shows up.

> Also, I do not see in the code that basemodel is not public. Why did you
> conclude this? If a user wants to implement a new model, shouldn't he
> inherit from basemodel? In that case it should be public. If that's not the
> case, an __all__ dict should be added to the module to indicate what is
> public and what is not.
>

I guess I am not using public/private right.  I was thinking private
== can't be instantiated, but what you say is correct (I will be using
it for generalized maxent, etc.), so I guess it's public.

Thanks,

Skipper