Enable sphinx linting. (ros2#4195)

This should help us catch a few more errors with incorrect syntax in restructured text. This requires a few minor changes to our existing documents. Signed-off-by: Chris Lalancette <[email protected]>
CursedRock17 · Mar 3, 2024 · 4934f47 · 4934f47
1 parent 39caeba
commit 4934f47
Show file tree

Hide file tree

Showing 8 changed files with 40 additions and 21 deletions.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -20,8 +20,25 @@ jobs:
       - name: Test doc8
         run: make test
 
+  lint:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies with pip
+        run: pip install --no-warn-script-location --user -r requirements.txt -c constraints.txt
+
+      - name: Lint
+        run: make lint
+
   build:
-    needs: test
+    needs: [test, lint]
     runs-on: ubuntu-22.04
     steps:
       - name: Checkout

diff --git a/Makefile b/Makefile
@@ -17,11 +17,14 @@ help:
 multiversion: Makefile
 	sphinx-multiversion $(OPTS) "$(SOURCE)" build/html
 	@echo "<html><head><meta http-equiv=\"refresh\" content=\"0; url=iron/index.html\" /></head></html>" > build/html/index.html
-	python3 make_sitemapindex.py
+	$(PYTHON) make_sitemapindex.py
 
 %: Makefile
 	@$(BUILD) -M $@ "$(SOURCE)" "$(OUT)" $(OPTS)
 
+lint:
+	sphinx-lint source
+
 test:
 	doc8 --ignore D001 --ignore-path build
 

diff --git a/constraints.txt b/constraints.txt
@@ -10,6 +10,7 @@ Jinja2==3.0.3
 MarkupSafe==2.0.1
 packaging==21.3
 pbr==5.8.0
+polib==1.2.0
 Pygments==2.17.2
 pyparsing==2.4.7
 pytz==2022.1
@@ -18,6 +19,7 @@ restructuredtext_lint==1.3.2
 snowballstemmer==2.2.0
 Sphinx==7.2.6
 sphinx-copybutton==0.5.2
+sphinx-lint==0.9.1
 sphinx-multiversion==0.2.4
 sphinx-rtd-theme==2.0.0
 sphinx-tabs==3.4.5

diff --git a/requirements.txt b/requirements.txt
@@ -3,6 +3,7 @@ docutils
 pip
 sphinx
 sphinx-copybutton
+sphinx-lint
 sphinx-multiversion
 sphinx-rtd-theme
 sphinx-tabs

diff --git a/source/The-ROS2-Project/Marketing.rst b/source/The-ROS2-Project/Marketing.rst
@@ -37,5 +37,3 @@ Available formats:
 * :download:`A4 (for print) <Marketing/documents/ros2-brochure-a4-print.pdf>`
 * :download:`US Letter (for web/email) <Marketing/documents/ros2-brochure-ltr-web.pdf>`
 * :download:`US Letter (for print) <Marketing/documents/ros2-brochure-ltr-print.pdf>`
-
-
diff --git a/source/The-ROS2-Project/Metrics.rst b/source/The-ROS2-Project/Metrics.rst
@@ -27,18 +27,16 @@ Add your suggestions on how to improve these reports by posting them to `ROS Dis
 Historical Metrics Reports
 ..........................
 
-* :download:`2023 <http://download.ros.org/downloads/metrics/metrics-report-2024-01.pdf>`
-* :download:`2022 <http://download.ros.org/downloads/metrics/metrics-report-2022-07.pdf>`
-* :download:`2021 <http://download.ros.org/downloads/metrics/metrics-report-2021-07.pdf>`
-* :download:`2020 <http://download.ros.org/downloads/metrics/metrics-report-2020-07.pdf>`
-* :download:`2019 <http://download.ros.org/downloads/metrics/metrics-report-2019-07.pdf>`
-* :download:`2018 <http://download.ros.org/downloads/metrics/metrics-report-2018-07.pdf>`
-* :download:`2017 <http://download.ros.org/downloads/metrics/metrics-report-2017-07.pdf>`
-* :download:`2016 <http://download.ros.org/downloads/metrics/metrics-report-2016-07.pdf>`
-* :download:`2015 <http://download.ros.org/downloads/metrics/metrics-report-2015-07.pdf>`
-* :download:`2014 <http://download.ros.org/downloads/metrics/metrics-report-2014-07.pdf>`
-* :download:`2013 <http://download.ros.org/downloads/metrics/metrics-report-2013-08.pdf>`
-* :download:`2012 <http://download.ros.org/downloads/metrics/metrics-report-2012-07.pdf>`
-* :download:`2011 <http://download.ros.org/downloads/metrics/metrics-report-2011-08.pdf>`
-
-
+* `2023 <http://download.ros.org/downloads/metrics/metrics-report-2024-01.pdf>`_
+* `2022 <http://download.ros.org/downloads/metrics/metrics-report-2022-07.pdf>`_
+* `2021 <http://download.ros.org/downloads/metrics/metrics-report-2021-07.pdf>`_
+* `2020 <http://download.ros.org/downloads/metrics/metrics-report-2020-07.pdf>`_
+* `2019 <http://download.ros.org/downloads/metrics/metrics-report-2019-07.pdf>`_
+* `2018 <http://download.ros.org/downloads/metrics/metrics-report-2018-07.pdf>`_
+* `2017 <http://download.ros.org/downloads/metrics/metrics-report-2017-07.pdf>`_
+* `2016 <http://download.ros.org/downloads/metrics/metrics-report-2016-07.pdf>`_
+* `2015 <http://download.ros.org/downloads/metrics/metrics-report-2015-07.pdf>`_
+* `2014 <http://download.ros.org/downloads/metrics/metrics-report-2014-07.pdf>`_
+* `2013 <http://download.ros.org/downloads/metrics/metrics-report-2013-08.pdf>`_
+* `2012 <http://download.ros.org/downloads/metrics/metrics-report-2012-07.pdf>`_
+* `2011 <http://download.ros.org/downloads/metrics/metrics-report-2011-08.pdf>`_
diff --git a/source/Tutorials/Advanced/Simulators/Gazebo/Gazebo.rst b/source/Tutorials/Advanced/Simulators/Gazebo/Gazebo.rst
@@ -191,7 +191,7 @@ There are two options:
 
         CTRL-C to quit
 
-        currently:	speed 0.5	turn 1.0
+        currently:      speed 0.5       turn 1.0
 
 3 Visualizing lidar data in ROS 2
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/source/Tutorials/Advanced/Simulators/Webots/Installation-MacOS.rst b/source/Tutorials/Advanced/Simulators/Webots/Installation-MacOS.rst
@@ -87,7 +87,7 @@ The following instructions and commands are all run inside the VM.
 
   .. code-block:: console
 
-      share	/home/ubuntu/shared	9p	trans=virtio,version=9p2000.L,rw,_netdev,nofail	0	0
+      share     /home/ubuntu/shared     9p      trans=virtio,version=9p2000.L,rw,_netdev,nofail 0       0
 
 * The environment variable ``WEBOTS_SHARED_FOLDER`` must always be set in order for the package to work properly in the VM.
   This variable specifies the location of the shared folder that is used to exchange data between the host machine and the virtual machine (VM) to the ``webots_ros2`` package.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -37,5 +37,3 @@ Available formats:
		* :download:`A4 (for print) <Marketing/documents/ros2-brochure-a4-print.pdf>`
		* :download:`US Letter (for web/email) <Marketing/documents/ros2-brochure-ltr-web.pdf>`
		* :download:`US Letter (for print) <Marketing/documents/ros2-brochure-ltr-print.pdf>`