Update documentation

mpenning · Nov 29, 2023 · 43773ee · 43773ee
1 parent 06e4ce8
commit 43773ee
Show file tree

Hide file tree

Showing 7 changed files with 238 additions and 48 deletions.
diff --git a/sphinx-doc/api.rst b/sphinx-doc/api.rst
@@ -15,4 +15,5 @@ This part of the documentation covers all the significant Python classes and met
    api_CiscoConfParse.rst
    api_ConfigList.rst
    api_Models_Cisco.rst
+   api_Models_Nxos.rst
    api_ccp_util.rst
diff --git a/sphinx-doc/factory.rst b/sphinx-doc/factory.rst
@@ -23,51 +23,9 @@ The most developed factory is ``ios``.
 .. warning::
    Anything about ``factory`` parsing can change at any time (but mostly does not).
 
-syntax='ios'
-------------
-
-syntax='ios', factory=True example
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-- Documentation for ``IOSIntfLine`` properties: :class:`~ciscoconfparse.models_cisco.IOSIntfLine()`.
-- This is an example of getting an :class:`~ciscoconfparse.ccp_util.IPv4Obj()` for an :class:`~ciscoconfparse.models_cisco.IOSIntfLine()` that was parsed with ``factory=True``.
-
-.. sourcecode:: python
-
-   >>> from ciscoconfparse import CiscoConfParse
-   >>> parse = CiscoConfParse("tests/fixtures/configs/sample_08.ios", syntax="ios", factory=True)
-   >>> hsrp_intfs = parse.find_parent_objects("interface", " standby")
-   >>>
-   >>> hsrp_intfs[0]
-   <IOSIntfLine # 231 'interface FastEthernet0/0' primary_ipv4: '172.16.2.1/24'>
-   >>>
-   >>> hsrp_intfs[0].ipv4
-   <IPv4Obj 172.16.2.1/24>
-   >>>
-
-syntax='ios', factory=False example
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This is the same operation with ``factory=False``; we expect an ``AttributeError`` because ``factory=False`` returns :class:`~ciscoconfparse.models_cisco.IOSCfgLine()` instances instead of :class:`~ciscoconfparse.models_cisco.IOSIntfLine()` instances (which have the ``ipv4`` attribute).
-
-.. sourcecode:: python
-
-   >>> from ciscoconfparse import CiscoConfParse
-   >>> parse = CiscoConfParse("tests/fixtures/configs/sample_08.ios", syntax="ios", factory=False)
-   >>> hsrp_intfs = parse.find_parent_objects("interface", " standby")
-   >>>
-   >>> hsrp_intfs[0]
-   <IOSCfgLine # 231 'interface FastEthernet0/0'>
-   >>>
-   >>> hsrp_intfs[0].ipv4
-   2023-11-18 07:00:21.216 | ERROR    | ciscoconfparse.ccp_abc:__getattr__:142 - The ipv4 attribute does not exist
-   2023-11-18 07:00:21.217 | ERROR    | __main__:<module>:1 - An error has been caught in function '<module>', process 'MainProcess' (111007), thread 'MainThread' (139675861627520):
-   Traceback (most recent call last):
-
-     File "/home/mpenning/fixme/ciscoconfparse/ciscoconfparse/ccp_abc.py", line 138, in __getattr__
-       retval = getattr(object, attr)
-                                └ 'ipv4'
-
-   AttributeError: type object 'object' has no attribute 'ipv4'
-   >>>
+Also See
+^^^^^^^^
 
+- The :ref:`syntax_ios` page.
+- The :ref:`syntax_nxos` page.
+- The :ref:`syntax_iosxr` page.
diff --git a/sphinx-doc/index.rst b/sphinx-doc/index.rst
@@ -12,6 +12,9 @@ Welcome to ciscoconfparse's documentation!
    legacy_syntax
    syntax_factory_intro
    syntax
+   syntax_ios
+   syntax_nxos
+   syntax_iosxr
    factory
    api
 

diff --git a/sphinx-doc/syntax.rst b/sphinx-doc/syntax.rst
@@ -11,9 +11,12 @@ This configuration parse reads the configuration as ``ios`` syntax by default:
 .. sourcecode:: python
 
    >>> from ciscoconfparse import CiscoConfParse
-   >>> parse = CiscoConfParse('/tftpboot/sfob09f02sw01.conf')
+   >>> parse = CiscoConfParse('/tftpboot/sfob09f02sw01.conf', factory=False)
    >>>
 
+.. warning::
+   Only set ``factory=True`` if you know what  you are doing.  See
+
 This configuration parse explicitly reads the configuration as ``asa`` syntax:
 
 .. sourcecode:: python
@@ -32,3 +35,6 @@ This configuration parse explicitly reads the configuration as ``asa`` syntax:
   - Is an interface a switchport?
   - Is an interface administratively shutdown?
 
+.. note::
+   If you are parsing a configuration that uses braces (such as JunOS), do not use ``syntax='ios'``; JunOS has dedicated syntax: ``syntax='junos'``.
+
diff --git a/sphinx-doc/syntax_ios.rst b/sphinx-doc/syntax_ios.rst
@@ -0,0 +1,74 @@
+.. _syntax_ios:
+
+============
+syntax='ios'
+============
+
+``syntax='ios'`` should be used for IOS-style configurations.  By default ``syntax='ios'`` is used and it's
+a good default for many vendor configurations (without braces).
+
+This configuration parse reads the configuration as ``ios`` syntax by default:
+
+.. sourcecode:: python
+
+   >>> from ciscoconfparse import CiscoConfParse
+   >>> parse = CiscoConfParse('/tftpboot/sfob09f02rtr01.conf')
+   >>>
+
+This is the same as using:
+
+.. sourcecode:: python
+
+   >>> from ciscoconfparse import CiscoConfParse
+   >>> parse = CiscoConfParse('/tftpboot/sfob09f02rtr01.conf', syntax='ios', factory=False)
+   >>>
+
+
+When using ``syntax='ios'`` also consider the ``factory`` setting; for more information, see the :ref:`factory` page.
+
+
+syntax='ios', factory=True example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Documentation for ``IOSIntfLine`` properties: :class:`~ciscoconfparse.models_cisco.IOSIntfLine()`.
+- This is an example of getting an :class:`~ciscoconfparse.ccp_util.IPv4Obj()` for an :class:`~ciscoconfparse.models_cisco.IOSIntfLine()` that was parsed with ``factory=True``.
+
+.. sourcecode:: python
+
+   >>> from ciscoconfparse import CiscoConfParse
+   >>> parse = CiscoConfParse("tests/fixtures/configs/sample_08.ios", syntax="ios", factory=True)
+   >>> hsrp_intfs = parse.find_parent_objects("interface", " standby")
+   >>>
+   >>> hsrp_intfs[0]
+   <IOSIntfLine # 231 'interface FastEthernet0/0' primary_ipv4: '172.16.2.1/24'>
+   >>>
+   >>> hsrp_intfs[0].ipv4
+   <IPv4Obj 172.16.2.1/24>
+   >>>
+
+syntax='ios', factory=False example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is the same operation with ``factory=False``; we expect an ``AttributeError`` because ``factory=False`` returns :class:`~ciscoconfparse.models_cisco.IOSCfgLine()` instances instead of :class:`~ciscoconfparse.models_cisco.IOSIntfLine()` instances (which have the ``ipv4`` attribute).
+
+.. sourcecode:: python
+
+   >>> from ciscoconfparse import CiscoConfParse
+   >>> parse = CiscoConfParse("tests/fixtures/configs/sample_08.ios", syntax="ios", factory=False)
+   >>> hsrp_intfs = parse.find_parent_objects("interface", " standby")
+   >>>
+   >>> hsrp_intfs[0]
+   <IOSCfgLine # 231 'interface FastEthernet0/0'>
+   >>>
+   >>> hsrp_intfs[0].ipv4
+   2023-11-18 07:00:21.216 | ERROR    | ciscoconfparse.ccp_abc:__getattr__:142 - The ipv4 attribute does not exist
+   2023-11-18 07:00:21.217 | ERROR    | __main__:<module>:1 - An error has been caught in function '<module>', process 'MainProcess' (111007), thread 'MainThread' (139675861627520):
+   Traceback (most recent call last):
+
+     File "/home/mpenning/fixme/ciscoconfparse/ciscoconfparse/ccp_abc.py", line 138, in __getattr__
+       retval = getattr(object, attr)
+                                └ 'ipv4'
+
+   AttributeError: type object 'object' has no attribute 'ipv4'
+   >>>
+
diff --git a/sphinx-doc/syntax_iosxr.rst b/sphinx-doc/syntax_iosxr.rst
@@ -0,0 +1,74 @@
+.. _syntax_iosxr:
+
+==============
+syntax='iosxr'
+==============
+
+``syntax='iosxr'`` should be used for Cisco IOS XR configurations.  By default ``syntax='ios'`` is used and it's
+a good default for many vendor configurations (without braces); however, ``syntax='iosxr'`` handles situations as described below.
+
+This configuration parse reads the configuration as ``iosxr`` syntax.
+
+.. sourcecode:: python
+
+   >>> from ciscoconfparse import CiscoConfParse
+   >>> parse = CiscoConfParse('/tftpboot/sfob09f02rtr01.conf', syntax='iosxr')
+   >>>
+
+This is the same as using:
+
+.. sourcecode:: python
+
+   >>> from ciscoconfparse import CiscoConfParse
+   >>> parse = CiscoConfParse('/tftpboot/sfob09f02rtr01.conf', syntax='iosxr', factory=False)
+   >>>
+
+
+When using ``syntax='iosxr'`` also consider the ``factory`` setting; for more information, see the :ref:`factory` page.
+
+
+syntax='iosxr', factory=True example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Documentation for ``IOSXRIntfLine`` properties: :class:`~ciscoconfparse.models_iosxr.IOSXRIntfLine()`.
+- This is an example of getting an :class:`~ciscoconfparse.ccp_util.IPv4Obj()` for an :class:`~ciscoconfparse.models_iosxr.IOSXRIntfLine()` that was parsed with ``factory=True``.
+
+.. sourcecode:: python
+
+   >>> from ciscoconfparse import CiscoConfParse
+   >>> parse = CiscoConfParse("tests/fixtures/configs/sample_01.iosxr", syntax="iosxr", factory=True)
+   >>> ipv4_intfs = parse.find_parent_objects("interface", "  ipv4 address")
+   >>>
+   >>> ipv4_intfs[0]
+   <IOSXRIntfLine # 120 'interface Loopback0' info: '100.2.3.20/32'>
+   >>>
+   >>> ipv4_intfs[0].ipv4
+   <IPv4Obj 10.10.248.50/24>
+   >>>
+
+syntax='iosxr', factory=False example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is the same operation with ``factory=False``; we expect an ``AttributeError`` because ``factory=False`` returns :class:`~ciscoconfparse.models_iosxr.IOSXRCfgLine()` instances instead of :class:`~ciscoconfparse.models_iosxr.IOSXRIntfLine()` instances (which have the ``ipv4`` attribute).
+
+.. sourcecode:: python
+
+   >>> from ciscoconfparse import CiscoConfParse
+   >>> parse = CiscoConfParse("tests/fixtures/configs/sample_01.iosxr", syntax="iosxr", factory=False)
+   >>> ipv4_intfs = parse.find_parent_objects("interface", "  ipv4 address")
+   >>>
+   >>> ipv4_intfs[0]
+   <IOSXRCfgLine # 120 'interface Loopback0'>
+   >>>
+   >>> ipv4_intfs[0].ipv4
+   2023-11-18 07:00:21.216 | ERROR    | ciscoconfparse.ccp_abc:__getattr__:142 - The ipv4 attribute does not exist
+   2023-11-18 07:00:21.217 | ERROR    | __main__:<module>:1 - An error has been caught in function '<module>', process 'MainProcess' (111007), thread 'MainThread' (139675861627520):
+   Traceback (most recent call last):
+
+     File "/home/mpenning/fixme/ciscoconfparse/ciscoconfparse/ccp_abc.py", line 138, in __getattr__
+       retval = getattr(object, attr)
+                                └ 'ipv4'
+
+   AttributeError: type object 'object' has no attribute 'ipv4'
+   >>>
+
diff --git a/sphinx-doc/syntax_nxos.rst b/sphinx-doc/syntax_nxos.rst
@@ -0,0 +1,74 @@
+.. _syntax_nxos:
+
+=============
+syntax='nxos'
+=============
+
+``syntax='nxos'`` should be used for Cisco NXOS configurations.  By default ``syntax='ios'`` is used and it's
+a good default for many vendor configurations (without braces); however, ``syntax='nxos'`` handles situations as described below.
+
+This configuration parse reads the configuration as ``nxos`` syntax.
+
+.. sourcecode:: python
+
+   >>> from ciscoconfparse import CiscoConfParse
+   >>> parse = CiscoConfParse('/tftpboot/sfob09f02rtr01.conf', syntax='nxos')
+   >>>
+
+This is the same as using:
+
+.. sourcecode:: python
+
+   >>> from ciscoconfparse import CiscoConfParse
+   >>> parse = CiscoConfParse('/tftpboot/sfob09f02rtr01.conf', syntax='nxos', factory=False)
+   >>>
+
+
+When using ``syntax='nxos'`` also consider the ``factory`` setting; for more information, see the :ref:`factory` page.
+
+
+syntax='nxos', factory=True example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Documentation for ``NXOSIntfLine`` properties: :class:`~ciscoconfparse.models_nxos.NXOSIntfLine()`.
+- This is an example of getting an :class:`~ciscoconfparse.ccp_util.IPv4Obj()` for an :class:`~ciscoconfparse.models_nxos.NXOSIntfLine()` that was parsed with ``factory=True``.
+
+.. sourcecode:: python
+
+   >>> from ciscoconfparse import CiscoConfParse
+   >>> parse = CiscoConfParse("tests/fixtures/configs/sample_01.nxos", syntax="nxos", factory=True)
+   >>> ipv4_intfs = parse.find_parent_objects("interface", " ip address")
+   >>>
+   >>> ipv4_intfs[0]
+   <NXOSIntfLine # 166 'interface mgmt0' info: '10.10.248.50/24'>
+   >>>
+   >>> ipv4_intfs[0].ipv4
+   <IPv4Obj 10.10.248.50/24>
+   >>>
+
+syntax='nxos', factory=False example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is the same operation with ``factory=False``; we expect an ``AttributeError`` because ``factory=False`` returns :class:`~ciscoconfparse.models_nxos.NXOSCfgLine()` instances instead of :class:`~ciscoconfparse.models_nxos.NXOSIntfLine()` instances (which have the ``ipv4`` attribute).
+
+.. sourcecode:: python
+
+   >>> from ciscoconfparse import CiscoConfParse
+   >>> parse = CiscoConfParse("tests/fixtures/configs/sample_01.nxos", syntax="nxos", factory=False)
+   >>> ipv4_intfs = parse.find_parent_objects("interface", " ip address")
+   >>>
+   >>> ipv4_intfs[0]
+   <NXOSCfgLine # 166 'interface mgmt0'>
+   >>>
+   >>> ipv4_intfs[0].ipv4
+   2023-11-18 07:00:21.216 | ERROR    | ciscoconfparse.ccp_abc:__getattr__:142 - The ipv4 attribute does not exist
+   2023-11-18 07:00:21.217 | ERROR    | __main__:<module>:1 - An error has been caught in function '<module>', process 'MainProcess' (111007), thread 'MainThread' (139675861627520):
+   Traceback (most recent call last):
+
+     File "/home/mpenning/fixme/ciscoconfparse/ciscoconfparse/ccp_abc.py", line 138, in __getattr__
+       retval = getattr(object, attr)
+                                └ 'ipv4'
+
+   AttributeError: type object 'object' has no attribute 'ipv4'
+   >>>
+