RTD: Incorporation of Howto files

[detlefarend]

Extensions of Appendix 1 as follows:

• Creation of submenus
  Basic Functions, Reinforcement Learning, Game Theory, UI Framework SciUI
• Prototype of a Howto (to be reviewed)
  To find the best way to document it. The following things should be possible/available:
  • Code box for a quick copy/paste of the sample code
  • Trial: Autodoc of the howto
• Incorporation of all Howtos
  • Howto 08 (Steve)
  • Howto 20 (Rizky)
  • Howto 22 (Yehia)
• Move Result section to above source code

[budiatmadjajaWill]

Autodoc of the howto is not what we had in mind. What we are doing is including the file itself.

[detlefarend]

Hi William,

the code box is fine. In addition to this it would be helpful if we could take over the module description as explanation above the code box. I hoped that it is possible by using autodoc functionality...

[detlefarend]

Then a further question. Does the code box support a copy function? Currently it is not really handy to take over the source code into my local ide.

[budiatmadjajaWill]

Hi Detlef, did you mistook the placement of the arrow? The picture you sent points the arrow of the Logging docstring to the Basic Function how to description.
Anyway, although we need to do it one by one, it should be possible to point to the docstring.

If you're saying about a simple click to copy functionality, there should be some third party extensions.
e.g:https://sphinx-copybutton.readthedocs.io/en/latest/
We can try this out if that's what you want. Note: this extension is applied to the whole site.

[budiatmadjajaWill]

Hi Detlef, did you mistook the placement of the arrow? The picture you sent points the arrow of the Logging docstring to the Basic Function how to description. Anyway, although we need to do it one by one, it should be possible to point to the docstring.

This isn't as straightforward as I thought it would be since the file name have spaces and parentheses. The file itself will also be run during the build process of the html.

[detlefarend]

Hi Detlef, did you mistook the placement of the arrow? The picture you sent points the arrow of the Logging docstring to the Basic Function how to description.

Anyway, although we need to do it one by one, it should be possible to point to the docstring.

If you're saying about a simple click to copy functionality, there should be some third party extensions.

e.g:https://sphinx-copybutton.readthedocs.io/en/latest/

We can try this out if that's what you want. Note: this extension is applied to the whole site.

You are right, the arrow is too long. The question is whether it is possible to take over the howto description(s) from the source code automatically.

[detlefarend]

If you're saying about a simple click to copy functionality, there should be some third party extensions.

e.g:https://sphinx-copybutton.readthedocs.io/en/latest/

We can try this out if that's what you want. Note: this extension is applied to the whole site.

That's a really nice solution. Could you please take over it?

[budiatmadjajaWill]

You are right, the arrow is too long. The question is whether it is possible to take over the howto description(s) from the source code automatically.

It is possible but it doesn't look good. We have to manually import the files one by one too. It's basically copy pasting the description one by one. The only advantage is that if the description is changed, which I don't think happens that often.

Personally, I'd say it's better to just type in the thing manually.

That's a really nice solution. Could you please take over it?

Yes, I'll take care of it tomorrow.

[detlefarend]

You are right, the arrow is too long. The question is whether it is possible to take over the howto description(s) from the source code automatically.

It is possible but it doesn't look good. We have to manually import the files one by one too. It's basically copy pasting the description one by one. The only advantage is that if the description is changed, which I don't think happens that often.

Personally, I'd say it's better to just type in the thing manually.

Agreed.

That's a really nice solution. Could you please take over it?

Yes, I'll take care of it tomorrow.

Thx!

[budiatmadjajaWill]

Before building the documentation, please do pip install sphinx-copybutton.

[detlefarend]

The copy button works fine!!

Question: you took over the descriptions manually, right? I am not sure whether this is really necessary. But for the moment please keep it as it is.

Then the menu item texts: I would prefer to take over the module name in the code (line 4) like "Howto 08 - (RL) Run own agents with petting zoo environment". We just have to make the numbers unique and maybe with 3 digits.

Question: does RTD support quickinfos in the menu? My vision: you move the cursor over a howto menu entry and then a quickinfo pops up with the description. Could you please check this? Thx!

[budiatmadjajaWill]

Question: you took over the descriptions manually, right? I am not sure whether this is really necessary. But for the moment please keep it as it is.

Yes, I was questioning myself about its necessity too.

Then the menu item texts: I would prefer to take over the module name in the code (line 4) like "Howto 08 - (RL) Run own agents with petting zoo environment". We just have to make the numbers unique and maybe with 3 digits.

I can change it quickly, I have a question about the howto on the GT module though, they start from 6. I think it's because they were in the same module as the RL howtos previously. Should I leave it like that ?

Question: does RTD support quickinfos in the menu? My vision: you move the cursor over a howto menu entry and then a quickinfo pops up with the description. Could you please check this? Thx!

This is the closest that I found, but I don't think this is what you want either. https://github.com/readthedocs/sphinx-hoverxref

[detlefarend]

Then the menu item texts: I would prefer to take over the module name in the code (line 4) like "Howto 08 - (RL) Run own agents with petting zoo environment". We just have to make the numbers unique and maybe with 3 digits.

I can change it quickly, I have a question about the howto on the GT module though, they start from 6. I think it's because they were in the same module as the RL howtos previously. Should I leave it like that ?

For the moment: yes.

Question: does RTD support quickinfos in the menu? My vision: you move the cursor over a howto menu entry and then a quickinfo pops up with the description. Could you please check this? Thx!

This is the closest that I found, but I don't think this is what you want either. https://github.com/readthedocs/sphinx-hoverxref

If I understand it right this functionality is not possible on menu items on the left, correct? Then it doesn't help us here. But: good to know about it...

[budiatmadjajaWill]

If I understand it right this functionality is not possible on menu items on the left, correct? Then it doesn't help us here. But: good to know about it...

Yes, it doesn't allow that. That is already in the realms of the theme itself and they don't have it as far as I know.

[detlefarend]

Hi William,
incorporating howtos is a recurring topic. Could you please prepare a template file for it with a structure like this:

• Title
• Date, Version
• Description
• Expected results (description, result plottings, images, screenshots, ...)
• Dependencies (with code box that contains package installation commands and/or commented links to the related pages with installation info)
• Code box including the sample code itself

The goal is that we create a new file based on this template and import it in the rtd menu structure.

[budiatmadjajaWill]

This template that you're talking about, it's an rst template instead of the code template, right? As in, we are planning to enrich the howto code with informations in the RTD.

[detlefarend]

This template that you're talking about, it's an rst template instead of the code template, right? As in, we are planning to enrich the howto code with informations in the RTD.

Yep. Creating a new howto means then: create the py module and a related copy from this template. Fill the rst file and include it in our menu. Then someone else reviews it by following the rtd description.

[detlefarend]

Question: the descriptions of the howtos above the code box was taken over manually, right?

[budiatmadjajaWill]

Question: the descriptions of the howtos above the code box was taken over manually, right?

Yes manually.

I will restructure the whole submenus so that they are contained by themselves.

[detlefarend]

Maybe it's better for the moment to work out one example. And if we found the best way to describe/present it then we can take over the necessary things for the rest of it.

[detlefarend]

I guess a missunderstanding. I had an rst file for each howto and a template for a howto rst file in my mind. So a developer who wants to provide a new howto creates two files: howto.py and howto.rst and includes the howto.rst into the related overarching rst file.
Then the hidden links in the template file: please provide them as ready to use lines and then comment every line separately. If my howto needs Gym I just want to uncomment the related line and then the entry appears like the MLPro entry

• MLPro
• OpenAI Gym
• PettingZoo

This should be later on included on the "PR_template" for contributing. So, you can read the instruction directly on the template. A step by step how to contribute.

Good idea. Contribution is anyway something to work out. I would also like to provide a step by step docu of how to "donate" an environment or policy.

[budiatmadjajaWill]

@rizkydiprasetya @detlefarend @steveyuwono
Please update the how to Dependencies and expected behaviour of the howtos that you guys make. I'm not sure what you guys want to add in this section. The dependency list in issue #163 is edited last month and I am not sure of its accuracy.
Thank you.

[detlefarend]

Hi @rizkydiprasetya, could you please check whether there is still something to do for Howto 20? The related task in the description is not yet ticked on. Thank you!