search

pymc-labs / pymc-marketing

Bayesian marketing toolbox in PyMC. Media Mix (MMM), customer lifetime value (CLV), buy-till-you-die (BTYD) models and more.
https://www.pymc-marketing.io/
Apache License 2.0
683 stars 190 forks source link

Remove full object path in docs #315

Closed wd60622 closed 9 months ago

wd60622 commented 1 year ago

Is it possible or desirable to remove the full paths to the functions and classes? I find it a bit congested, repetitive, and not working on some screen dimensions. The alternative might be easier on the eyes too.

Screenshot 2023-07-02 at 13 02 06

Alternative would be 

clv
    distributions
    models 
        basic
        beta_geo
            BetaGeoModel
        ...
    plotting 
    utils 
mmm

and also reflected in the top breadcrumbs as well as top object name.

I'd be willing to look into implementing

wd60622 commented 9 months ago

I think in order to do this, the tree has to be manually defined. Like in the pymc docs

ricardoV94 commented 9 months ago

@OriolAbril should be able to confirm if there's no more automatic way

wd60622 commented 9 months ago

Looking at the source code from autodocs Not sure that it is an option

OriolAbril commented 9 months ago

I'll run some tests. There are multiple elements to consider though, all seem to be the name, but are different concepts.

I think the title (in blue) and the text shown in the sidebar will be the same thing. This can be the name only (not the full import path) and I think I can change it. This should be doable with autosummary templates. I can open a PR and see from there.

The object name (in black right below, here prepended by class) should, in my opinion, show the full import path where you expect users to import that object from. Users don't need to know about the specific file a function is found in, i.e. I expect everyone to use pymc.sample, so the docs should use that; the fact that sample is actually in pymc.sampling.mcmc is either useless or confusing for the average user (note this is currently wrong in the PyMC docs but there is a PR open already). However, this can make it impossible to have completely automatic api docs generation and may force you to list all the objects in the public api with their preferred import path (that's it though, only listing them and once it's done it only needs changing if the public api changes).

Yet a different element is the url for that page, over which there is significantly less control but there might also be some ways of shortening it.