docs: resolve sphinx warnings

Signed-off-by: Xuehai Pan <XuehaiPan@pku.edu.cn>

.readthedocs.yaml

@@ -15,7 +15,7 @@ build:
 sphinx:
   builder: html
   configuration: docs/source/conf.py
-  fail_on_warning: false
+  fail_on_warning: true
 
 # Optionally declare the Python requirements required to build your docs
 python:

docs/README.md

@@ -0,0 +1,22 @@
+# The `nvitop`'s Documentation
+
+This directory contains the documentation of `nvitop`, the one-stop solution for GPU process management.
+
+### Requirements  <!-- markdownlint-disable heading-increment -->
+
+- `sphinx`
+- `sphinx-autoapi`
+- `sphinx-autobuild`
+- `sphinx-copybutton`
+- `sphinx-rtd-theme`
+- `make`
+
+### Steps to build the documentation  <!-- markdownlint-disable heading-increment -->
+
+```bash
+cd docs  # navigate to this directory
+python3 -m venv --upgrade-deps .venv
+source .venv/bin/activate
+pip3 install -r ../requirements.txt -r requirements.txt
+sphinx-autobuild --watch ../nvitop --open-browser source build
+```

docs/requirements.txt

@@ -1,6 +1,8 @@
-sphinx
-sphinx-rtd-theme
+sphinx >= 5.0
+sphinx-autoapi
+sphinx-autobuild
 sphinx-copybutton
+sphinx-rtd-theme
 
 pytorch-lightning >= 1.5.0
 tensorflow >= 2.0

docs/source/apis/core/libnvml.rst

@@ -6,3 +6,4 @@ nvitop.core.libnvml module
     :undoc-members:
     :show-inheritance:
     :member-order: bysource
+    :noindex: pynvml.NVMLError

docs/source/apis/index.rst

@@ -22,3 +22,4 @@ Module contents
     :members:
     :undoc-members:
     :show-inheritance:
+    :member-order: bysource

docs/source/conf.py

@@ -4,6 +4,8 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+# pylint: disable=all
+
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -102,8 +104,13 @@ html_css_files = [
 #
 # html_sidebars = {}
 
+suppress_warnings = [
+    'ref.python'
+]
+
 extlinks = {
-    'gitcode': ('https://github.com/XuehaiPan/nvitop/blob/HEAD/%s', '')
+    'gitcode': ('https://github.com/XuehaiPan/nvitop/blob/HEAD/%s', '%s'),
+    'issue': ('https://github.com/XuehaiPan/nvitop/issues/%s', 'issue %s')
 }
 
 

nvitop/core/collector.py

@@ -40,8 +40,8 @@ def take_snapshots(
         devices (Optional[Union[Device, Iterable[Device]]]):
             Requested devices for snapshots. If not given, the devices will be
             determined from GPU processes:
-                - All devices (no GPU processes are given)
-                - Devices that used by given GPU processes
+            - All devices (no GPU processes are given)
+            - Devices that used by given GPU processes
         gpu_processes (Optional[Union[GpuProcess, Iterable[GpuProcess]]]):
             Requested GPU processes snapshots. If not given, all GPU processes
             running on the requested device will be returned.

nvitop/core/device.py

@@ -275,8 +275,8 @@ class Device:  # pylint: disable=too-many-instance-attributes,too-many-public-me
             indices (Iterable[Union[int, Tuple[int, int]]]):
                 Indices of the devices. For each index, get ``PhysicalDevice`` for single int
                 and ``MigDevice`` for tuple (int, int). That is:
-                    - (int)        -> PhysicalDevice
-                    - ((int, int)) -> MigDevice
+                - (int)        -> PhysicalDevice
+                - ((int, int)) -> MigDevice
 
         Returns: List[Union[PhysicalDevice, MigDevice]]
             A list of ``PhysicalDevice`` and/or ``MigDevice`` instances of the given indices.