Extended examples should be in Example section

[pmaroneh]

Currently the Extended examples (Brake Squeal, Cart-Pole, etc) are very difficult to find on the website as they are placed in the "User Guide" section. These examples should be in the "Examples" section so that new users can find them, or, if this is not possible, a new "Extended Examples" section should be added at the top next to Examples

[germa89]

Hi @pmaroneh

I totally agree that the current location is a bit... weird.

It has a reason though. The extended examples are "too big" to be run every time we do a PR/Push/Release. Therefore these extended examples have been "static-ed" which means, they have been run once, and the results keep. So when we build documentation we just reuse the previous data. This is fast, but it does not serve for "validation".

I will look into a way to harmonize this. Thank you!

[pmaroneh]

Hi @germa89 Yes, I remember that we talked about this and that there is a good reason to have the Extended Examples and the Examples separate. I believe it is very important to make the Extended Examples easier to find, as someone curious about the package will probably go straight to the examples to see what can be done with it. Since the Extended Examples are the most complex ones, they really highlight the purpose of the package, so they should be very easy to find. Perhaps a new tab as I suggested could work? Let me know if I can be of help.

[germa89]

From the Sphinx-Gallery documentation (https://sphinx-gallery.github.io/stable/syntax.html#plain-rst-examples):

Sphinx-Gallery generates examples from Python scripts, so examples written in plain RST files are not supported. If you’re looking to generate hyperlinks for functions (linking to their corresponding online documentation) in code blocks of ordinary RST documentation, you might find sphinx-codeautolink helpful.

I think changing the place of the extended examples will require more work than expected. Maybe re-write the static examples as py files.

[germa89]

I was wrong, it is work, but not as much as expected.

Please @pmaroneh could you have a look at #1029 and see if it is what you had in mind?

[pmaroneh]

That's great news @germa89 ! #1029 is perfect!!