Develop api documentation update #5325
Conversation
Added Python Low Level API Documentation in addition to How to Use document. Added link to API documentation in How to Use document.
Updating with main.
|
|
chriselion
requested review from
vincentpierre
and removed request for
chriselion
There was a problem hiding this comment.
- It seems to be just a markdownification of the docstrings of the mlagents_envs package. I do not see how this is useful.
- I assume (hope) you used a tool to generate this documentation and I think it would be a lot more useful if this PR contained the code to generate this documentation. You could also have a pre-commit hook to detect changes on the mlagents_envs package and regenerate the markdown when needed. This would be much more future-proof!
Perhaps. But at least one user/customer does find it useful, and likely more do as well. Also, I can think of several reasons why this would be useful:
Yes, of course this was automatically generated. I used pydoc-markdown to generate the api docs. I can include the yaml config file for it in the mlagents_envs package. Great idea. I'll add this in.
Great suggestion. I was originally going to do that, but I wasn't sure what the team's best practices are/were. I'll add this in. |
Syncing with main.
…ng pydoc-markdown
| modules: | ||
| - name: mlagents_envs | ||
| file_name: Python-API-Documentation.md | ||
| submodules: |
There was a problem hiding this comment.
Is there a way to simplify these submodules? Which files are included and which are not.
I was to make sure that if the organization of the files change or if the content of the files change there will be minimal changes to this file.
There was a problem hiding this comment.
Unfortunately, you need to specify which modules explicitly when using pydoc-markdown. We have two options with pydoc-markdown:
- Build all the docs for the entire package, or
- Specify which modules/sub-modules to build the docs for
This is as simple as it's going to get. If there's a major refactoring to the API, e.g. package architecture changes, module renaming, etc., we have no choice but to update these files. If the content of the modules changes, pydoc-markdown should pick that up automatically with no changes to this config.
ml-agents-envs/pydoc-config.yaml
Outdated
| - name: mlagents_envs | ||
| file_name: Python-API-Documentation.md | ||
| submodules: | ||
| - env_utils |
There was a problem hiding this comment.
I do not think env_utils, communicator, registry.binary_utils, registry.remote_registry_entry, registry.base_registry_entry and maybe more should not be a part of this.
There was a problem hiding this comment.
Ok. I'll remove.
|
Feel free to merge #5369 into this branch when the tests pass. |
.github/workflows/pre-commit.yml
Outdated
| - name: Install dependencies | ||
| run: | | ||
| python -m pip install --upgrade pip | ||
| pip install pydoc-markdown |
There was a problem hiding this comment.
This needs to be a fixed version in case the pydoc-markdown has a breaking update.
* Some edits to the documentation * fix precommit * Update ml-agents-envs/mlagents_envs/base_env.py * regenerating markdown
There was a problem hiding this comment.
Have you considered adding the link to the new markdown on this page? https://github.com/Unity-Technologies/ml-agents/tree/main/docs#api-docs
I think it would give this new doc more visibility.
Feel free to merge with or without this suggestion.
Thank you for your work!
Proposed change(s)
Describe the changes made in this PR.
Useful links (Github issues, JIRA tickets, ML-Agents forum threads etc.)
Types of change(s)
Checklist
Other comments
Adding API documentation for the mlagents_envs package.