Doc: Update API

aristanetworks · Jul 18, 2023 · 54e7f16 · 54e7f16
1 parent 661addc
commit 54e7f16
Show file tree

Hide file tree

Showing 30 changed files with 121 additions and 87 deletions.
diff --git a/docs/api/device.md b/docs/api/device.md
@@ -1,9 +1,8 @@
-# AntaDevice Abstracted class
+### ::: anta.device.AntaDevice
+    options:
+      filters: ["!^_[^_]", "!__(eq|rich_repr)__"]
 
-::: anta.device.AntaDevice
-    heading_level: 2
+### ::: anta.device.AsyncEOSDevice
+    options:
+      filters: ["!^_[^_]", "!__(eq|rich_repr)__"]
 
-# AsyncEOSDevice class
-
-::: anta.device.AsyncEOSDevice
-    heading_level: 2
diff --git a/docs/api/inventory.md b/docs/api/inventory.md
@@ -1,9 +1,5 @@
-# ANTA Inventory module
+### ::: anta.inventory.AntaInventory
+    options:
+        filters: ["!^_[^_]", "!__str__"]
 
-::: anta.inventory.AntaInventory
-    heading_level: 2
-
-# Exceptions
-
-::: anta.inventory.exceptions
-    heading_level: 2
+### ::: anta.inventory.exceptions
diff --git a/docs/api/inventory.models.input.md b/docs/api/inventory.models.input.md
@@ -1,15 +1,7 @@
-# Data models for anta.inventory
+### ::: anta.inventory.models.AntaInventoryInput
 
-::: anta.inventory.models.AntaInventoryInput
-    heading_level: 2
+### ::: anta.inventory.models.AntaInventoryHost
 
-# User inventory components
+### ::: anta.inventory.models.AntaInventoryNetwork
 
-::: anta.inventory.models.AntaInventoryHost
-    heading_level: 2
-
-::: anta.inventory.models.AntaInventoryNetwork
-    heading_level: 2
-
-::: anta.inventory.models.AntaInventoryRange
-    heading_level: 2
+### ::: anta.inventory.models.AntaInventoryRange
diff --git a/docs/api/models.md b/docs/api/models.md
@@ -1,14 +1,7 @@
-# AntaTest definition
+### ::: anta.models.AntaTest
+    options:
+        filters: ["!^_[^_]", "!__init_subclass__"]
 
-::: anta.models.AntaTest
-    heading_level: 2
+### ::: anta.models.AntaCommand
 
-# AntaCommand definition
-
-::: anta.models.AntaCommand
-    heading_level: 2
-
-# AntaTemplate definition
-
-::: anta.models.AntaTemplate
-    heading_level: 2
+### ::: anta.models.AntaTemplate
diff --git a/docs/api/report_manager.md b/docs/api/report_manager.md
@@ -1,4 +1 @@
-# ANTA ReportManager module
-
-::: anta.reporter.ReportTable
-    heading_level: 2
+### ::: anta.reporter.ReportTable
diff --git a/docs/api/report_manager_models.md b/docs/api/report_manager_models.md
@@ -1,4 +1 @@
-# ColorManager Entry
-
-::: anta.reporter.models.ColorManager
-    heading_level: 2
+### ::: anta.reporter.models.ColorManager
diff --git a/docs/api/result_manager.md b/docs/api/result_manager.md
@@ -1,4 +1,3 @@
-# ANTA ResultManager module
-
-::: anta.result_manager.ResultManager
-    heading_level: 2
+### ::: anta.result_manager.ResultManager
+      options:
+        filters: ["!^_[^_]", "!^__len__"]
diff --git a/docs/api/result_manager_models.md b/docs/api/result_manager_models.md
@@ -1,9 +1,7 @@
-# TestResult Entry
+### ::: anta.result_manager.models.TestResult
+    options:
+        filters: ["!^_[^_]", "!__str__"]
 
-::: anta.result_manager.models.TestResult
-    heading_level: 2
-
-# ListResult
-
-::: anta.result_manager.models.ListResult
-    heading_level: 2
+### ::: anta.result_manager.models.ListResult
+      options:
+        filters: ["!^_[^_]", "!^__(len|getitem|iter)__",]
diff --git a/docs/api/tests.aaa.md b/docs/api/tests.aaa.md
@@ -1,4 +1,6 @@
-# ANTA catalog for AAA tests
+# ANTA catalog for interfaces tests
 
 ::: anta.tests.aaa
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.configuration.md b/docs/api/tests.configuration.md
@@ -1,4 +1,6 @@
 # ANTA catalog for configuration tests
 
 ::: anta.tests.configuration
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.connectivity.md b/docs/api/tests.connectivity.md
@@ -1,4 +1,6 @@
 # ANTA catalog for connectivity tests
 
 ::: anta.tests.connectivity
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.field_notices.md b/docs/api/tests.field_notices.md
@@ -1,4 +1,6 @@
 # ANTA catalog for Field Notices tests
 
 ::: anta.tests.field_notices
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.hardware.md b/docs/api/tests.hardware.md
@@ -1,4 +1,6 @@
 # ANTA catalog for hardware tests
 
 ::: anta.tests.hardware
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.interfaces.md b/docs/api/tests.interfaces.md
@@ -1,4 +1,6 @@
 # ANTA catalog for interfaces tests
 
 ::: anta.tests.interfaces
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.logging.md b/docs/api/tests.logging.md
@@ -1,4 +1,6 @@
 # ANTA catalog for logging tests
 
 ::: anta.tests.logging
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.mlag.md b/docs/api/tests.mlag.md
@@ -1,4 +1,6 @@
 # ANTA catalog for mlag tests
 
 ::: anta.tests.mlag
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.multicast.md b/docs/api/tests.multicast.md
@@ -1,4 +1,6 @@
 # ANTA catalog for multicast tests
 
 ::: anta.tests.multicast
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.profiles.md b/docs/api/tests.profiles.md
@@ -1,4 +1,6 @@
 # ANTA catalog for profiles tests
 
 ::: anta.tests.profiles
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.routing.bgp.md b/docs/api/tests.routing.bgp.md
@@ -1,4 +1,6 @@
 # ANTA catalog for routing-bgp tests
 
 ::: anta.tests.routing.bgp
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.routing.generic.md b/docs/api/tests.routing.generic.md
@@ -1,4 +1,6 @@
 # ANTA catalog for routing-generic tests
 
 ::: anta.tests.routing.generic
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.routing.ospf.md b/docs/api/tests.routing.ospf.md
@@ -1,4 +1,6 @@
 # ANTA catalog for routing-ospf tests
 
 ::: anta.tests.routing.ospf
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.security.md b/docs/api/tests.security.md
@@ -1,4 +1,6 @@
 # ANTA catalog for security tests
 
 ::: anta.tests.security
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.snmp.md b/docs/api/tests.snmp.md
@@ -1,4 +1,6 @@
 # ANTA catalog for SNMP tests
 
 ::: anta.tests.snmp
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.software.md b/docs/api/tests.software.md
@@ -1,4 +1,6 @@
 # ANTA catalog for software tests
 
 ::: anta.tests.software
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.stp.md b/docs/api/tests.stp.md
@@ -1,4 +1,6 @@
 # ANTA catalog for STP tests
 
 ::: anta.tests.stp
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/api/tests.system.md b/docs/api/tests.system.md
@@ -1,5 +1,7 @@
 # ANTA catalog for system tests
 
 ::: anta.tests.system
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
 
diff --git a/docs/api/tests.vxlan.md b/docs/api/tests.vxlan.md
@@ -1,4 +1,6 @@
 # ANTA catalog for VxLAN tests
 
 ::: anta.tests.vxlan
-    heading_level: 3
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -5,8 +5,7 @@ mkdocs-git-revision-date-localized-plugin>=1.1.0
 mkdocs-git-revision-date-plugin>=0.3.2
 mkdocs-material>=8.3.9
 mkdocs-material-extensions>=1.0.3
-mkdocstrings>=0.19.0
-mkdocstrings-python>=0.7.1
+mkdocstrings[python]>=0.20.0
 mdx_truly_sane_lists
 fontawesome_markdown
 mike==1.1.2
diff --git a/docs/stylesheets/extra.material.css b/docs/stylesheets/extra.material.css
@@ -198,3 +198,10 @@
     /* width: 50%; */
   }
 }
+
+/* mkdocstrings css from official repo to indent sub-elements nicely */
+/* Indentation. */
+div.doc-contents {
+  padding-left: 25px;
+  border-left: .05rem solid var(--md-typeset-table-color);
+}
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -71,20 +71,37 @@ extra_javascript:
   - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/highlight.min.js
 
 watch:
-  # Watch src/ directory to reload on changes to docstrings for mkdocstrings
-  # plugin.
   - docs
+  # Watch src/ directory to reload on changes to docstrings for mkdocstrings plugin.
+  - anta
 
 plugins:
   - mkdocstrings:
       default_handler: python
       handlers:
         python:
+          paths: [anta]
+          import:
+            - https://docs.python.org/3/objects.inv
+            - https://mkdocstrings.github.io/objects.inv
+            - https://mkdocstrings.github.io/griffe/objects.inv
           options:
-            show_root_heading: false
-            show_source: true
-      watch:
-        - anta
+            docstring_options:
+              ignore_init_summary: true
+            docstring_section_style: table
+            heading_level: 2
+            inherited_members: false
+            merge_init_into_class: true
+            separate_signature: true
+            show_root_heading: true
+            show_root_full_path: false
+            show_signature_annotations: true
+            # sadly symbols are for insiders only
+            # https://mkdocstrings.github.io/python/usage/configuration/headings/#show_symbol_type_toc
+            # show_symbol_type_heading: true
+            # show_symbol_type_toc: true
+            # default filters here
+            filters: ["!^_[^_]"]
   - search:
       lang: en
   - git-revision-date-localized:
@@ -172,6 +189,8 @@ nav:
     - Inventory: 
       - Inventory module: api/inventory.md
       - Inventory models: api/inventory.models.input.md
+    - Device:
+      - Device models: api/device.md
     - Test:
       - Test models: api/models.md
     - Result Manager: