Add documentation spelling check (#2032)

* Add sphinx spelling check.

* Fix spelling.

* Fix type test.

* Apply suggestions from code review

Co-authored-by: adai <[email protected]>

* Add spell checking test.

* Fix libenchant install.

* Attempt CI install fix with libenchant-dev.

* Fix spelling whitelisted.

* Fix git call issue.

---------

Co-authored-by: adai <[email protected]>

.github/workflows/ci-format.yml

@@ -88,6 +88,10 @@ jobs:
         uses: actions/checkout@v2
         with:
           fetch-depth: 0
+      - name: Install Enchant
+        run: |
+          apt-get update --fix-missing
+          apt-get install -y libenchant-dev
       - name: Build Sphinx documentation
         run: |
           python3.8 -m venv ${{env.venv_dir}}
@@ -96,7 +100,7 @@ jobs:
           pip install wheel==0.38.4
           pip install .[camera_obs,doc,train,ray,envision,argoverse,opendrive,waymo]
           cd ${GITHUB_WORKSPACE}/docs
-          make html SPHINXOPTS="-W -T -E --keep-going"
+          make html SPHINXOPTS="-W -T -E --keep-going -b spelling"
       - name: Check build output
         run: |
           cd $GITHUB_WORKSPACE

cli/benchmark.py

@@ -41,7 +41,7 @@ def benchmark_cli():
     "--debug-log",
     is_flag=True,
     default=False,
-    help="Log the benchmark in stdout.",
+    help="Log the benchmark in ``stdout``.",
 )
 @click.option(
     "--benchmark-listing",

cli/zoo.py

@@ -77,7 +77,7 @@ def manager(port):
 
 @zoo_cli.command(
     name="install",
-    help="Attempt to install the specified agents from the given paths/url",
+    help="Attempt to install the specified agents from the given URI path.",
 )
 @click.argument(
     "agent_paths",

docs/benchmarks/agent_zoo.rst

@@ -3,7 +3,7 @@
 Agent Zoo
 =========
 
-Numerous prebuilt and trained agents are hosted at `zoo/policies <https://github.com/huawei-noah/SMARTS/tree/master/zoo/policies>`_ . 
+Numerous pre-built and trained agents are hosted at `zoo/policies <https://github.com/huawei-noah/SMARTS/tree/master/zoo/policies>`_ . 
 These agents should be installed prior to being used in SMARTS environments or benchmarks.
 
 .. code-block:: bash
@@ -31,7 +31,7 @@ Contribute agents
 First, add the new agent to `zoo/policies <https://github.com/huawei-noah/SMARTS/tree/master/zoo/policies>`_. It should contain 
 
 * package setup file,
-* inference code with prebuilt model, and
+* inference code with pre-built model, and
 * algorithm explanation.
 
 Then, register the newly added zoo agent in `zoo/policies/__init__.py <https://github.com/huawei-noah/SMARTS/tree/master/zoo/policies/__init__.py>`_.
@@ -44,7 +44,7 @@ Available zoo agents
    :header-rows: 1
 
    * - Agent locator and path
-     - Benchmark or Env
+     - Benchmark or Environment
      - Action space
      - Source
      - Remarks

docs/benchmarks/benchmark.rst

@@ -6,7 +6,7 @@ Instructions
 A benchmark is a standard set of rigorous environments which can be used to 
 assess and compare the performance of agents built by various researchers. 
 
-:doc:`Agent Zoo </benchmarks/agent_zoo>` contains prebuilt and trained agents 
+:doc:`Agent Zoo </benchmarks/agent_zoo>` contains pre-built and trained agents 
 which could be deployed as reference ego agent in the benchmarks. Feel free to 
 mix and match compatible agents and benchmarks.
 
@@ -89,7 +89,7 @@ The list of benchmarks from the custom benchmark listing file can be examined as
 Benchmark listing file
 ----------------------
 
-The benchmark listing file is organised as below.
+The benchmark listing file is organized as below.
 
 .. code:: yaml
 

docs/benchmarks/driving_smarts_2022.rst

@@ -14,16 +14,16 @@ Refer to :func:`~smarts.env.gymnasium.driving_smarts_2022_env.driving_smarts_202
 
 In each driving scenario, the ego-agents must drive towards their respective mission goal locations. Each agent's mission goal is given in the observation returned by the environment at each time step. 
 The mission goal could be accessed as ``observation.ego_vehicle_state.mission.goal.position`` which gives an ``(x, y, z)`` map coordinate of the goal location.
-Any method such as reinforcement learning, offline reinforcement learning, behaviour cloning, generative models, predictive models, etc, may be used to develop the policy.
+Any method such as reinforcement learning, offline reinforcement learning, behavior cloning, generative models, predictive models, etc, may be used to develop the policy.
 
 The scenario names and their missions are as follows. The desired task execution is illustrated by a trained baseline agent, which uses PPO algorithm from `Stable Baselines3 <https://github.com/DLR-RM/stable-baselines3>`_ reinforcement learning library.
 
 + 1_to_2lane_left_turn_c
-    A single ego agent must make a left turn at an uprotected cross-junction.
+    A single ego agent must make a left turn at an unprotected cross-junction.
 
     .. image:: /_static/driving_smarts_2022/intersection-c.gif
 + 1_to_2lane_left_turn_t 
-    A single ego agent must make a left turn at an uprotected T-junction.
+    A single ego agent must make a left turn at an unprotected T-junction.
 
     .. image:: /_static/driving_smarts_2022/intersection-t.gif
 + 3lane_merge_multi_agent

docs/benchmarks/driving_smarts_2023_1.rst

@@ -42,15 +42,15 @@ below.
 
     Here, egos are in red colour, and background traffic is in silver colour.
 
-Any method such as reinforcement learning, offline reinforcement learning, behaviour cloning, generative models,
+Any method such as reinforcement learning, offline reinforcement learning, behavior cloning, generative models,
 predictive models, etc, may be used to develop the policy.
 
 Several scenarios are provided for training. Their names and tasks are as follows. 
 The desired task execution is illustrated in a gif by a trained baseline agent. 
 
 .. todo::
 
-    Provide sample training scenarios and corresponding gifs showing a baseline model traversing the map.
+    Provide sample training scenarios and corresponding ``.gif`` images showing a baseline model traversing the map.
 
 Observation space
 -----------------
@@ -92,14 +92,14 @@ the user.
     ├── setup.cfg                
     └── setup.py                
 
-1. inference/contrib_policy/__init__.py
+1. ``inference/contrib_policy/__init__.py``
     + Keep this file unchanged.
     + It is an empty file.
 
-2. inference/contrib_policy/policy.py
+2. ``inference/contrib_policy/policy.py``
     + Must contain a ``class Policy(Agent)`` class which inherits from :class:`~smarts.core.agent.Agent`.
 
-3. inference/__init__.py
+3. ``inference/__init__.py``
     + Must contain the following template code. 
     + The template code registers the user's policy in SMARTS agent zoo.
 
@@ -147,10 +147,10 @@ the user.
       + :attr:`~smarts.core.agent_interface.AgentInterface.neighborhood_vehicle_states`, and 
       + :attr:`~smarts.core.agent_interface.AgentInterface.waypoint_paths`. 
 
-4. inference/MANIFEST.in 
+4. ``inference/MANIFEST.in``
     + Contains any file paths to be included in the package.
 
-5. inference/setup.cfg
+5. ``inference/setup.cfg``
     + Must contain the following template code. 
     + The template code helps build the user policy into a Python package.
 
@@ -182,7 +182,7 @@ the user.
     + Do **not** add SMARTS package as a dependency in the ``install_requires`` section.
     + Dependencies in the ``install_requires`` section **must** have an exact package version specified using ``==``.
 
-6. inference/setup.py
+6. ``inference/setup.py``
     + Keep this file and its default contents unchanged.
     + Its default contents are shown below.
 

docs/benchmarks/driving_smarts_2023_3.rst

@@ -31,7 +31,7 @@ The episode ends when the leader reaches its destination. Ego agents do not have
 destination. Additionally, the ego terminates whenever it collides, drives off road, or exceeds maximum number 
 of steps per episode.
 
-Any method such as reinforcement learning, offline reinforcement learning, behaviour cloning, generative models,
+Any method such as reinforcement learning, offline reinforcement learning, behavior cloning, generative models,
 predictive models, etc, may be used to develop the policy.
 
 Several scenarios are provided for training. Their names and tasks are as follows. 
@@ -82,14 +82,14 @@ the user.
     ├── setup.cfg                
     └── setup.py                
 
-1. inference/contrib_policy/__init__.py
+1. ``inference/contrib_policy/__init__.py``
     + Keep this file unchanged.
     + It is an empty file.
 
-2. inference/contrib_policy/policy.py
+2. ``inference/contrib_policy/policy.py``
     + Must contain a ``class Policy(Agent)`` class which inherits from :class:`~smarts.core.agent.Agent`.
 
-3. inference/__init__.py
+3. ``inference/__init__.py``
     + Must contain the following template code. 
     + The template code registers the user's policy in SMARTS agent zoo.
 
@@ -137,10 +137,10 @@ the user.
       + :attr:`~smarts.core.agent_interface.AgentInterface.neighborhood_vehicle_states`, and 
       + :attr:`~smarts.core.agent_interface.AgentInterface.waypoint_paths`. 
 
-4. inference/MANIFEST.in 
+4. ``inference/MANIFEST.in``
     + Contains any file paths to be included in the package.
 
-5. inference/setup.cfg
+5. ``inference/setup.cfg``
     + Must contain the following template code. 
     + The template code helps build the user policy into a Python package.
 
@@ -172,7 +172,7 @@ the user.
     + Do **not** add SMARTS package as a dependency in the ``install_requires`` section.
     + Dependencies in the ``install_requires`` section **must** have an exact package version specified using ``==``.
 
-6. inference/setup.py
+6. ``inference/setup.py``
     + Keep this file and its default contents unchanged.
     + Its default contents are shown below.
 

docs/conf.py

@@ -43,6 +43,7 @@
     "sphinx_rtd_theme",  # Read The Docs theme
     "sphinx_click",  # extract documentation from a `click` application
     "sphinxcontrib.apidoc",
+    "sphinxcontrib.spelling",
 ]
 
 extlinks = {
@@ -106,6 +107,13 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+# -- Options for spelling ----------------------------------------------------
+spelling_exclude_patterns = ["ignored_*", "**/*_pb2*"]
+spelling_ignore_pypi_package_names = True
+spelling_show_suggestions = True
+spelling_suggestion_limit = 2
+spelling_ignore_contributor_names=False
+spelling_word_list_filename = ["spelling_wordlist.txt"]
 
 # -- Options for HTML output -------------------------------------------------
 

docs/ecosystem/ngsim.rst

@@ -3,7 +3,7 @@
 NGSIM
 =====
 
-**NGSIM** is the Next Generation Simulation dataset, a free to use dataset created
+``NGSIM`` is the Next Generation Simulation dataset, a free to use dataset created
 by the US Department of Transportation (DOT) and described
 `here <https://ops.fhwa.dot.gov/trafficanalysistools/ngsim.htm>`__.
 
@@ -19,7 +19,7 @@ Its import scripts were tested on and work with the data downloaded from `here <
 which is the same as was used by this `PPUU project <https://github.com/Atcold/pytorch-PPUU>`_.
 
 After the dataset has been downloaded, you will need to update each ``scenario.py``
-in the ngsim scenario directories (e.g., :scenarios:`NGSIM/i80/scenario.py`, :scenarios:`NGSIM/us101/scenario.py`, and/or :scenarios:`NGSIM/peachtree/scenario.py`) to point the `input_path` field
+in the ``NGSIM`` scenario directories (e.g., :scenarios:`NGSIM/i80/scenario.py`, :scenarios:`NGSIM/us101/scenario.py`, and/or :scenarios:`NGSIM/peachtree/scenario.py`) to point the `input_path` field
 to the dataset location on your filesystem.
 
 Once that is done, you should be able to build your scenarios in the normal way, for example: ``scl scenario build-all --clean scenarios/NGSIM``

docs/ecosystem/rllib.rst

@@ -1,27 +1,28 @@
 .. _rllib:
 
+
 RLlib
 =====
 
 **RLlib** is an open-source library for reinforcement learning that offers both high scalability and a unified API for a variety
-of applications. RLlib natively supports TensorFlow, TensorFlow Eager, and PyTorch. Most of its internals are agnostic to such
+of applications. ``RLlib`` natively supports ``TensorFlow``, ``TensorFlow Eager``, and ``PyTorch``. Most of its internals are agnostic to such
 deep learning frameworks.
 
 Recommended reads
 -----------------
 
-RLlib is implemented on top of Ray. Ray is a distributed computing framework specifically designed with RL in mind. There are
-many docs about Ray and RLlib. We recommend to read the following pages first,
+``RLlib`` is implemented on top of ``Ray``. ``Ray`` is a distributed computing framework specifically designed with RL in mind. There are
+many docs about ``Ray`` and ``RLlib``. We recommend to read the following pages first,
 
-- `RLlib in 60 seconds <https://docs.ray.io/en/latest/rllib.html#rllib-in-60-seconds>`_: Getting started with RLlib.
+- `RLlib in 60 seconds <https://docs.ray.io/en/latest/rllib.html#rllib-in-60-seconds>`_: Getting started with ``RLlib``.
 - `Common Parameters <https://docs.ray.io/en/latest/rllib-training.html#common-parameters>`_: Common `tune` configs.
 - `Basic Python API <https://docs.ray.io/en/latest/rllib-training.html#basic-python-api>`_: Basic `tune.run` function.
 - `Callbacks and Custom Metrics <https://docs.ray.io/en/latest/rllib-training.html#callbacks-and-custom-metrics>`_: About callbacks and metrics.
 - `Visualizing Custom Metrics <https://docs.ray.io/en/latest/rllib-training.html#visualizing-custom-metrics>`_: How to use TensorBoard to visualize metrics.
 - `Built-in Models and Preprocessors <https://docs.ray.io/en/latest/rllib-models.html#default-behaviours>`_: Built-in preprocessor, including how to deal with different observation spaces.
-- `Proximal Policy Optimization (PPO) <https://docs.ray.io/en/latest/rllib-algorithms.html#proximal-policy-optimization-ppo>`_: RLlib PPO implementation and PPO parameters.
+- `Proximal Policy Optimization (PPO) <https://docs.ray.io/en/latest/rllib-algorithms.html#proximal-policy-optimization-ppo>`_: ``RLlib`` PPO implementation and PPO parameters.
 - `PopulationBasedTraining <https://docs.ray.io/en/latest/tune/api_docs/schedulers.html#populationbasedtraining>`_: Population Based Training algorithm and examples.
-- `RLlib Examples <https://docs.ray.io/en/latest/rllib-examples.html>`_: Get to know RLlib quickly through examples.
+- `RLlib Examples <https://docs.ray.io/en/latest/rllib-examples.html>`_: Get to know ``RLlib`` quickly through examples.
 
 
 Resume training

docs/resources/containers.rst

@@ -28,7 +28,7 @@ SMARTS docker images are hosted at `dockerhub <https://hub.docker.com/u/huaweino
     # Visit http://localhost:8081 in the host machine to see the running simulation in Envision.
 
 Singularity (Apptainer)
------------------------
+---------------------------
 
 Instructions for running SMARTS within a `singularity <https://apptainer.org/>`_ container.
 

docs/resources/contributing.rst

@@ -23,8 +23,8 @@ We encourage all forms of contributions to SMARTS, not limited to:
 + Patches
 + Test cases
 
-Setting up your dev environment
--------------------------------
+Setting up your development environment
+---------------------------------------
 
 In addition to following the :ref:`setup` steps, you will need to install the ``[dev]`` dependencies.
 
@@ -88,7 +88,7 @@ Documentation
 
 All project code API, features, examples, etc, should be documented using `reStructuredText <https://www.sphinx-doc.org/>`_ at ``SMARTS/docs``. The docs are generated by Sphinx and hosted at `https://smarts.readthedocs.io/ <https://smarts.readthedocs.io/>`_.
 
-All public python code interface should have `Google <https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings>`_ styled comments and docstrings. Sphinx provides an `example <https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html>`_ Google style Python docstrings.
+All public python code interface should have `Google <https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings>`_ styled comments and ``"docstrings"``. Sphinx provides an `example <https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html>`_ Google style Python ``"docstrings"``.
 
 Execute the following to build the docs locally.
 

docs/resources/todo.rst

@@ -3,6 +3,6 @@
 TODO List
 =========
 
-A list of current documentation TODO.
+A list of current documentation TODOs.
 
-.. todolist_::
+.. todolist_::

docs/setup.rst

@@ -6,8 +6,8 @@ Setup
 Prerequisites
 -------------
 
-+ python3 (3.8 or 3.9)
-+ ubuntu (>=16.04)
++ ``python3 (3.8 or 3.9)``
++ ``ubuntu (>=16.04)``
 
 Installation
 ------------

docs/sim/agent.rst

@@ -282,7 +282,7 @@ Here, ``max_episode_steps`` controls the max steps allowed for the agent in an e
 
 .. note:: 
 
-    While using RLlib, the ``max_episode_steps`` control authority may be ceded to RLlib through their config option ``horizon``, but doing so 
+    While using ``RLlib``, the ``max_episode_steps`` control authority may be ceded to ``RLlib`` through their config option ``horizon``, but doing so 
     removes the ability to customize different max episode steps for each agent.
 
 A pre-configured `interface` can be extended by supplying extra `kwargs`. For example the following extends `AgentType.Standard` pre-configured interface to include lidar observation.
@@ -344,7 +344,7 @@ Spaces
 Spaces provide samples for variation. For reference on spaces, see `gymnasium <https://gymnasium.farama.org/api/spaces/>`_ .
 SMARTS environments contains (i) ``observation_space`` and (ii) ``action_space`` attributes, which are dictionaries mapping agent ids to their corresponding observation or action spaces, respectively.
 
-Consider a SMARTS env with an agent named `Agent_001`. If `Agent_001`'s `interface` is customised, then the agent's corresponding observation space (i.e., ``env.observation_space["Agent_001"]``) and action space (i.e., ``env.action_space["Agent_001"]``) from the environment would be changed accordingly. 
+Consider a SMARTS env with an agent named `Agent_001`. If `Agent_001`'s `interface` is customized, then the agent's corresponding observation space (i.e., ``env.observation_space["Agent_001"]``) and action space (i.e., ``env.action_space["Agent_001"]``) from the environment would be changed accordingly. 
 
 Policy
 ------

docs/sim/bubbles.rst

@@ -7,8 +7,8 @@ SMARTS provides the concept of a spatial-temporal bubble which allows for focuse
 
 A bubble covers an area and filters traffic vehicles that pass through that zone. A vehicle entering the bubble will first pass into an ``airlock`` buffer area of ``shadowing`` where an agent may begin observing from the vehicle.  The agent may then fully take over control of that vehicle when it enters the bubble proper. SMARTS will replace control of the traffic vehicles with the agents specified by the bubble definition.  The bubble agent will relinquish its control to a suitable traffic provider when its controlled vehicle exits the bubble and airlock regions.
 
-Limtations
-----------
+Limitations
+-----------
 
 If a vehicle whose trajectory is being provided from a traffic history dataset is taken over by an agent within a bubble, the vehicle generally cannot be returned to the trajectory specified in the history dataset upon bubble exit without a "jump" or "glitch" due to the plurality of situations where there is a divergence of vehicle states from the history within the bubble.  So instead, the simple SMARTS traffic provider assumes control of it at this point and will attempt to navigate it to its original destination, avoiding collisions along the way.
 

docs/sim/cli.rst

@@ -1,5 +1,9 @@
 .. _cli: 
 
+.. spelling:word-list::
+
+   scl
+
 Command Line Interface
 ======================
 

docs/sim/configuration.rst

@@ -8,7 +8,7 @@ You can change the behavior of the underlying SMARTS engine.
 Configuration of the engine can come from several sources. These locations take precedence as noted:
 
 1. Individual ``SMARTS_`` prefixed environment variables (e.g. ``SMARTS_SENSOR_WORKER_COUNT``)
-2. Local directory engine configuration (./smarts_engine.ini )
+2. Local directory engine configuration (``./smarts_engine.ini``)
 3. Local user engine configuration, ``~/.smarts/engine.ini``, if local directory configuration is not found.
 4. Global engine configuration, ``/etc/smarts/engine.ini``, if local configuration is not found.
 5. Package default configuration, ``$PYTHON_PATH/smarts/engine.ini``, if global configuration is not found.
@@ -24,4 +24,4 @@ These settings are as follows:
 
 .. todo::
 
-    List engine settings
+    List engine settings