Specific Plans for Documentation Website

[jkterry1]

The current plans for the documentation website are as follows:

PettingZoo's website is made with Jekyll, which essentially builds the website from specifically formatted .md files. For this reason, PettingZoo's documentation website can be reused with new .md files filled out and an afternoon worth of changes. PettingZoo had a planned upgrade to a new and dramatically nicer Jekyll template based on this design a UI/UX designer (www.michellebohnen.design) created for me:
https://www.figma.com/file/eY64qwYYBA6L0HSBKje5fZ/PettingZoo-High-Fidelity?node-id=0%3A1 (a wrappers page will be added). I plan to wait until conversion is done before updating the Gym website because I think the new version really is much better. This is planned to be done by the end of August.

Right now, @Kyle-Sang and @ZachariahRosenberg are working on the planned upgrades to the PettingZoo Jekyll template (and will later work on adapting it to Gym). @RyanNavillus is in charge of creating the .md files of actual documentation for the MuJuCo and robotics environments, @alfred100p is in charge of creating the .md files for the Algorithm and Toy Text environments and @ZachariahRosenberg is (tentatively) in charge of creating the .md files for the Atari, classic control and Box2d environments. @RyanNavillus is also in charge of documenting wrappers.

[araffin]

quick question because it is not clear to me: is auto-generated doc also included in the plan?

[jkterry1]

What do you mean?

[araffin]

What do you mean?

maybe with an example it becomes clearer...
In SB3, we have two types of doc:

1. doc that is manually written (most of the user guide), for instance https://stable-baselines3.readthedocs.io/en/master/guide/custom_policy.html
2. doc that is automatically generated from the code docstrings (mostly the api and all helper classes/functions), which ensures that it is always up to date and also improves code quality: https://stable-baselines3.readthedocs.io/en/master/modules/ppo.html#parameters

I was refering to 2)

[jkterry1]

I don't intend to add that in the initial website release due to time constraints and how the website code we're stealing works. We similarly also don't intend to have the initial website have amazing mobile support.

Once the website works at all, and the presumably large number of problems people find with it are fixed and all the dust settles, we'd greatly appreciate contributions from the community to both ends (and I've gotten an extraordinary number of people asking to help with documentation, more I'm able to take). Automatically pulling from code when building in Jekyll shouldn't be be totally doable though and that's definitely a good idea.

[araffin]

Automatically pulling from code when building in Jekyll shouldn't be be totally doable though and that's definitely a good idea.

I have no idea how it works with Jekyll... most people (including Transformers or PyTorch) use Sphinx (and it seems pytorch uses it in combination with jeklyll).
The other advantage of auto-generated doc is that is it a good incentive to writing better docstrings ;)

[jkterry1]

That was a typo. I meant to say that it /should/ be totally doable with Jekyll.

I just view this as a problem to worry about after a website already exists.

[jkterry1]

@shreyansjainn is going to be working on a draft of the general API documentation, as well as a list of recent and tutorials for Gym.

[tristandeleu]

@jkterry1 Any reason not to go with Sphinx, as suggested #2276 (comment)? This looks like a very good option for writing documentation, it has cross-references and auto-generated documentation from docstrings, and many popular libraries already use it.

[RyanNavillus]

@jkterry1 Any reason not to go with Sphinx, as suggested #2276 (comment)? This looks like a very good option for writing documentation, it has cross-references and auto-generated documentation from docstrings, and many popular libraries already use it.

The argument for not using Sphinx alone is that it's not a great format for documenting environments, which is obviously a significant part of gym. I worked on a large portion of the PettingZoo documentation, and the freedom you get from a full standalone website is nice for displaying that type of information. I've only used Sphinx a few times so I could be wrong, but I think that Sphinx/readthedocs would require us to document environments in a fairly straightforward list view, which isn't ideal. A standalone site allows us to display environment information more concisely, like in a gallery view, which is what PettingZoo and Gym's current websites do (albeit with very sparse environment documentation for gym).

Of course, gym is not just a collection of environments, it also has a significant codebase that needs to be documented for users and developers, which would probably be better served by autogenerated documentation than manually written .md files.

Ideally, there's a solution that allows us to add autogenerated documentation to a standalone site, or that allows us to document environments effectively using Sphinx. Maybe someone with more experience using Sphinx can chime in here.

Edit: Here is an example of autogenerated documentation for RL environments on readthedocs for reference. In my opinion, this does a good job of documenting the code features of the environment, but not the RL features like action and observation spaces.

[jkterry1]

"Ideally, there's a solution that allows us to add autogenerated documentation to a standalone site"

We can, and will, do this. Managing Gym otherwise would be untenable. Kyle has been working on it today actually. I believe I mentioned that in this thread awhile ago.

[jkterry1]

@tristandeleu the text in your PR will be used; Kyle can refactor it into the new format for you when you're later on in the process if you'd like.

[tristandeleu]

I plan to wait until conversion is done before updating the Gym website because I think the new version really is much better. This is planned to be done by the end of August.

Any update on the documentation @jkterry1? It looks like little progress has been made in the past 2 months.

The argument for not using Sphinx alone is that it's not a great format for documenting environments, which is obviously a significant part of gym. [...] I've only used Sphinx a few times so I could be wrong, but I think that Sphinx/readthedocs would require us to document environments in a fairly straightforward list view, which isn't ideal. A standalone site allows us to display environment information more concisely, like in a gallery view, which is what PettingZoo and Gym's current websites do.

I'm no expert in Sphinx, but this absolutely sounds like something that can be done with Sphinx. The process can even be automated (reading the docstrings, getting the observation_space/action_space, the different versions of the environment, etc...), since documentation can be generated via extensions in Python.

[mgoulao]

I have been using the new documentation website and I have some things to add to the discussion. I have found the new website very difficult to navigate: the right sidebar is confusing, and it's not very obvious what it is; the left sidebar is uncomfortable to read and the submenus' UX is not great; the layout of the environments pages is confusing and inconsistent (e.g. from Atari to Breakout); finally, auto-generated documentation should be a must for this kind of project and the current version doesn't offer that.

So, I decided to develop a simple proof-of-concept using Sphinx, as suggested by @araffin, that tries to have the same features as the current version while having auto-generated doc and an improved UI and UX.
You can find the source code here and the webpage here
Note: The conversion from Markdown to reStructuredTex created problems in some tables, but nothing that can't be fixed.

[jkterry1]

I'll reply to this later in terms of UI/UX, but our current system already does fully autogenerate documentation?

…

On Wed, Mar 2, 2022 at 12:58 PM Manuel Goulão ***@***.***> wrote: I have been using the new documentation website <https://www.gymlibrary.ml/> and I have some things to add to the discussion. I have found the new website very difficult to navigate: the right sidebar is confusing, and it's not very obvious what it is; the left sidebar is uncomfortable to read and the submenus' UX is not great; the layout of the environments pages is confusing and inconsistent (e.g. from Atari to Breakout); finally, auto-generated documentation should be a must for this kind of project and the current version doesn't offer that. So, I decided to develop a simple proof-of-concept using Sphinx, as suggested by @araffin <https://github.com/araffin>, that tries to have the same features as the current version while having auto-generated doc and an improved UI and UX. You can find the source code here <https://github.com/mgoulao/gym-docs> and the webpage here <https://mgoulao.github.io/gym-docs/> Note: The conversion from Markdown to reStructuredTex created problems in some tables, but nothing that can't be fixed. — Reply to this email directly, view it on GitHub <#2276 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEUF33AO2ZU5KXQNSN5PFV3U56T3VANCNFSM5BI3J2OA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[jkterry1]

@mgoulao I sat down and went through this in more detail with @trigaten.

A few comments:
-I like the aesthetic and the handling of menus and the subheaders in the right hand bar better than what we have now, you're completely right about this upgrade.
-The organization of items in the base and documentation menus would need to be changed, but that's a fairly easy fix.
-I don't understand your objections to the current pages for individual environments, or why you like the current layout of them?
-FWIW this site genuinely isn't any more automated to build than what we already have

Do you want to email me at [email protected] and set up a time to call?

[jkterry1]

Everything is up on gymlibrary.ml now