[DOC] Allow easier access to different doc pages about pyswarms HOT 7 CLOSED

I think this could be resolved by calling "API Documentation" a section (not a subsection)

from pyswarms.

Hi @stsievert , sorry I just saw this now. Thank you for the feedback and I’ll work on this right away.

from pyswarms.

Hi @stsievert ,

I accomplished moving the API Documentation subsection in its own section, which I think is a really good suggestion, but the problem

Going from two pages on the documentation requires going to an intermediate page. For example, going from discrete.binary to [single.global_best module] requires two clicks.

still persists. It turns out that one really has to click the specific package (pyswarms.single or pyswarms.discrete) to access the modules inside of it.

I'm thinking of removing the upper-level hierarchy (pyswarms.single, pyswarms.discrete), but I prefer PR #64 's set-up more because it divides the optimizers wrt the specific problem they're trying to solve (i.e. single-objective, discrete-optim). This also provides a good structure in case we expand to different problem types (e.g. pyswarms.multi or pyswarms.constrained for multi-objective and constrained).

I'm still looking for a JS workaround to automatically expose all the modules right away without having to click, but it might take more time.

What do you think?

• Browser: Google Chrome

Move API Documentation as a new Section

Comparison

discrete.binary	single.global_best

from pyswarms.

A JS solution feels like a hack, and it looks like reduced the number of clicks required to navigate (ie, going from optimizers to utilizes looks easier).

from pyswarms.

Hi @stsievert ,

A JS solution feels like a hack

Well I feel the same way. I think it's part of Sphinx that the dropdown only appears depending on the page you are in.

Another way would be to remove the package hierarchy altogether (single, discrete), so as to expose the modules inside (global_best, local_best, discrete)— but I believe it's better to maintain the current structure, so the problem domains are much clearer (and scalable if new variants come in the future). What do you think?

it looks like reduced the number of clicks required to navigate (ie, going from optimizers to utilizes looks easier).

Yes it does, your suggestion to move API Documentation up one section is actually good. Thanks! 👍

from pyswarms.

to remove the package hierarchy altogether (single, discrete),

I think the hierarchy should stay, it sounds like it adds some useful information.

reduced the number of clicks required to navigate ... Yes it does

Then this issue is addressed. I’m comfortable closing it.

from pyswarms.

Thanks a lot, @stsievert !

Merged #64

from pyswarms.