"View full listing" for meta examples

[karlnapf]

Every meta example on the website should have a tab that says "show full code listing", which allows a user to see all of the example code, not just the snippets

Requires some web-hacking skills... not THAT easy, but not impossible

Start from the sphinx plugin:

For that, you will have to modify the sphinx plugin we wrote to render the meta examples, see https://github.com/shogun-toolbox/shogun/blob/develop/doc/cookbook/extensions/sgexample.py

[novate]

I would like to do this in my GSoC project, here are my initial ideas:

1. Enclose the unclosured initial meta example .sg code with #![initial_code]. This work could be done automatically with python.
2. Modify all .rst files. Add .. sgexample:: something.sg:initial_code. This work could also be done automatically with python.
3. To show full code, we could add . sgexample:: something.sg at the end of each .rst files, and modify sgexample.py to make the full code hide initially.

By doing procedures 1 and 2, we can make all cookbook with full content of example code. By doing procedure 3, we can add a “show full list” feature to our cookbook.

I'm currently learning sphinx, so I may have a more detailed idea on how to modify sgexample.py.

[karlnapf]

Hi thanks for taking this up!

1. is not really necessary. We do explicitly extract code in sgexample.py so we can just extract all there.
2. modifying the .rst files is not really a good idea since it requires so many changes. Rather we want to change how the page is generated in the python script mentioned above
3. same as above

I think the best way to change things is to start playing with the web page template that is used and then take it from there

[karlnapf]

Hey, any updates or questions here?

[novate]

Yes, I do have some updates:

1. I agree that we'd better modify .rst file as few as we could, while I think that the .rst file may still be modified, for we want to show full code. However .rst files haven't contained all of them yet. Such a modification could be easy if we write an automated snippet. We could discuss on how to make the modification less and easy to be done.
2. I agree that the crucial part is to modify sphinx-related code, and I have checked some of the doc pages generated by sphinx:
   • The most famous one is The Python Documentation Tutorials. For each code block, they added a small button at the upper-right corner to toggle interactive prompts like >>> or .... Here is an Example. We could learn from their design by adding a button with show full code written on it, and once we hit that button, we could see full code. Such a feature is done with a JS snippet, in which button.parent().find('.go, .gp, .gt').hide(); hides words in elements with class go, gp and gt.
   • Here is another example from SQLAlchemy Tutorial where they have a likewise small SQL button to toggle full code (closer to our demand). Their approach is to contain related code in their .rst file, and in this snippet, they wrote a function initSQLPopups() to control whether to pop-up or to close an already prepared popup-sql div by modifying css.

Looking forward to a further discussion!

[karlnapf]

Yeah exactly this is what we want, the >>>-style button that just shows all of the code in the file

[novate]

Here's a question: Do we have other code for our sphinx doc pages, or all we have is a python sphinx generator sgexample.py? If the latter is right, what can we do to add js snippets in it?

[karlnapf]

I am not exactly sure what you mean, but the sgexample.py is pretty much all that generates the cookbook pages along with the .rst and the .py, .cpp, .java, etc

[vinx13]

@novate We have some static files and the html template in https://github.com/shogun-toolbox/shogun/tree/develop/doc/cookbook/source

[novate]

Thanks! I get it. Now I know that we have other code for the cookbook pages, and all static things like js snippets could be placed at here.

[karlnapf]

Ah yes and it’s bootstrap!

[karlnapf]

any updates here @novate ?

[karlnapf]

This is still open