Develop api documentation update (#5325)

* Python Low Level API Documentation

Added Python Low Level API Documentation in addition to How to Use document. Added link to API documentation in How to Use document.

* Fixed pre-commit issues with docstrings in mlagents-env base_env

* Added local precommit hook to autogenerate markdown documentation using pydoc-markdown

* Updated github precommit workflow to install pydoc-markdown

* Updated github precommit workflow to fix pydoc-markdown install order.

* Some refactoring and docstring updates.

* Removed modules from doc generation as per https://github.com/Unity-Technologies/ml-agents/pull/5325#discussion_r632838268

* Some edits to the documentation (#5369)

* Some edits to the documentation

* fix precommit

* Update ml-agents-envs/mlagents_envs/base_env.py

* regenerating markdown

* Added fixed version to pydoc-markdown precommit install.

* Updated docs readme to add link to new Python API document...

.github/workflows/pre-commit.yml

     - uses: actions/setup-dotnet@v1
       with:
         dotnet-version: '3.1.x'
+    - name: Install dependencies
+      run: |
+          python -m pip install --upgrade pip
+          pip install pydoc-markdown==3.10.1
     - uses: pre-commit/action@v2.0.0
 
   markdown-link-check:

.pre-commit-config.yaml

         name: validate release links
         language: script
         entry: utils/validate_release_links.py
+    -   id: generate-markdown-docs
+        name: generate markdown docs
+        language: script
+        entry: utils/generate_markdown_docs.py --package_dirs ml-agents-envs
+        pass_filenames: false

docs/Python-API.md

 Unity Environments using our implementations of reinforcement learning or
 imitation learning. This document describes how to use the `mlagents_envs` API.
 For information on using `mlagents-learn`, see [here](Training-ML-Agents.md).
+For Python Low Level API documentation, see [here](Python-API-Documentation.md).
 
 The Python Low Level API can be used to interact directly with your Unity
 learning environment. As such, it can serve as the basis for developing and

docs/Readme.md

 ## API Docs
 
 - [API Reference](API-Reference.md)
+- [Python API Documentation](Python-API-Documentation.md)
 - [How to use the Python API](Python-API.md)
 - [How to use the Unity Environment Registry](Unity-Environment-Registry.md)
 - [Wrapping Learning Environment as a Gym (+Baselines/Dopamine Integration)](../gym-unity/README.md)

ml-agents-envs/mlagents_envs/base_env.py

 """
-Python Environment API for the ML-Agents toolkit
+Python Environment API for the ML-Agents Toolkit
 The aim of this API is to expose Agents evolving in a simulation
 to perform reinforcement learning on.
 This API supports multi-agent scenarios and groups similar Agents (same
 
 class DimensionProperty(IntFlag):
     """
-    No properties specified.
+    The dimension property of a dimension of an observation.
+    No properties specified.
+    """
+
+    NONE = 1
+    """
-    NONE = 1
+
+    TRANSLATIONAL_EQUIVARIANCE = 2
-    TRANSLATIONAL_EQUIVARIANCE = 2
+
+    VARIABLE_SIZE = 4
-    VARIABLE_SIZE = 4
 
 
 class ObservationType(Enum):
     """
 
-    # Observation information is generic.
-    # Observation contains goal information for current task.
+    """
+    Observation information is generic.
+    """
+
+    """
+    Observation contains goal information for current task.
+    """
 
 
 class ObservationSpec(NamedTuple):

ml-agents-envs/pydoc-config.yaml

+# config to specify which modules will be used to render api docs
+folder: docs
+modules:
+    - name: mlagents_envs
+      file_name: Python-API-Documentation.md
+      submodules:
+        - base_env
+        - environment
+        - registry
+        - registry.unity_env_registry
+        - side_channel
+        - side_channel.raw_bytes_channel
+        - side_channel.outgoing_message
+        - side_channel.engine_configuration_channel
+        - side_channel.side_channel_manager
+        - side_channel.stats_side_channel
+        - side_channel.incoming_message
+        - side_channel.float_properties_channel
+        - side_channel.environment_parameters_channel
+        - side_channel.side_channel

utils/generate_markdown_docs.py

+#!/usr/bin/env python3
+import os
+import subprocess
+import sys
+import yaml
+import argparse
+import hashlib
+
+
+# pydoc-markdown -I . -m module_name --render_toc > doc.md
+
+
+def hash_file(filename):
+    """
+    Calculate the md5 hash of a file. Used to check for stale files.
+
+    :param filename: The name of the file to check
+    :type str:
+    :return: A string containing the md5 hash of the file
+    :rtype: str
+    """
+    if os.path.exists(filename):
+        hasher = hashlib.md5()
+        with open(filename, "rb") as file_to_hash:
+            buffer = file_to_hash.read()
+            hasher.update(buffer)
+        return hasher.hexdigest()
+    else:
+        return 0
+
+
+def remove_trailing_whitespace(filename):
+    """
+    Removes trailing whitespace from a file.
+
+    :param filename: The name of the file to process
+    :type str:
+    """
+    num_changed = 0
+    # open the source file
+    with open(filename, "rb") as f:
+        source_file = f.read().decode()
+    # grab all the lines, removing the trailing whitespace
+    lines = [line.rstrip() for line in source_file.splitlines()]
+
+    # process lines to construct destination file
+    while lines and not lines[-1]:
+        lines.pop(-1)
+    lines.append("")
+    destination_file = "\n".join(lines)
+
+    # compare source and destination and write only if changed
+    if source_file != destination_file:
+        num_changed += 1
+        with open(filename, "wb") as f:
+            f.write(destination_file.encode())
+
+
+if __name__ == "__main__":
+    """
+    Pre-commit hook to generate Python API documentation using pydoc-markdown
+    and write as markdown files. Each package should have a config file,
+    pydoc-config.yaml, at the root level that provides configurations for
+    the generation. Fails if documentation was updated, passes otherwise. This
+    allows for pre-commit to fail in CI/CD and makes sure dev commits the doc
+    updates.
+    """
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--package_dirs", nargs="+")
+    args = parser.parse_args()
+
+    ok = False
+    return_code = 0
+    for package_dir in args.package_dirs:
+        config_path = os.path.join(os.getcwd(), package_dir, "pydoc-config.yaml")
+        print(config_path)
+        with open(config_path) as config_file:
+            config = yaml.full_load(config_file)
+            for module in config["modules"]:
+                module_name = module["name"]
+                submodules = module["submodules"]
+                output_file_name = f"./{config['folder']}/{module['file_name']}"
+                old_hash = hash_file(output_file_name)
+                module_args = []
+                for submodule in submodules:
+                    module_args.append("-m")
+                    module_args.append(f"{module_name}.{submodule}")
+                with open(output_file_name, "w") as output_file:
+                    subprocess_args = [
+                        "pydoc-markdown",
+                        "-I",
+                        f"./{package_dir}",
+                        *module_args,
+                        "--render-toc",
+                    ]
+                    subprocess.check_call(subprocess_args, stdout=output_file)
+                remove_trailing_whitespace(output_file_name)
+                new_hash = hash_file(output_file_name)
+                ok = old_hash == new_hash
+
+        return_code = 0 if ok else 1
+
+    sys.exit(return_code)