Update documentation

dev_tools/deploy_docs/deploy_docs.go

@@ -28,7 +28,7 @@ func main() {
 
 	// Start a new goph ssh connection with private key auth...
 	logoru.Info("    Initialize ssh key-auth")
-	auth, err := goph.Key("/home/mpenning/.ssh/id_ed25519", "")
+	auth, err := goph.Key("/home/mpenning/.ssh/id_rsa", "")
 	if err != nil {
 		logoru.Critical(err.Error())
 	}

sphinx-doc/factory.rst

@@ -0,0 +1,67 @@
+=======
+factory
+=======
+
+``factory`` is an experimental feature to derive more information about configurations by using
+several different configuration objects for a given ``syntax``.
+
+.. sourcecode:: python
+
+   >>> from ciscoconfparse import CiscoConfParse
+   >>> parse = CiscoConfParse('/tftpboot/sfob09f02sw01.conf', syntax='ios', factory=True)
+   >>> hsrp_intf = parse.find_parent_objects("interface", " standby")
+   >>>
+
+The most developed factory is ``ios``.
+
+.. note::
+   ``factory`` is an experimental feature; to enable it, parse with ``factory=True``.
+   If something doesn't work, it's a feature, not a bug.
+
+.. warning::
+   Anything about ``factory`` parsing can change at any time (but mostly does not).
+
+factory=True example
+--------------------
+
+This is an example of getting an :class:`~ciscoconfparse.ccp_util.IPv4Obj()` for an interface 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>
+   >>>
+
+factory=False example
+---------------------
+
+This is the same operation with ``factory=False``.
+
+.. 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'
+   >>>
+

sphinx-doc/index.rst

@@ -10,6 +10,9 @@ Welcome to ciscoconfparse's documentation!
    installation
    tutorial
    legacy_syntax
+   syntax_factory_intro
+   syntax
+   factory
    license_copyright
    api
 

sphinx-doc/legacy_syntax.rst

@@ -201,7 +201,7 @@ Sometimes you find yourself wishing you could decrypt vty or console passwords t
 
 .. note::
 
-   Cisco IOS Type 7 passwords were never meant to be secure; these passwords only protect against shoulder-surfing.  When you add users and enable passwords to your router, be sure to use Cisco IOS Type 5 passwords; these are much more secure and cannot be decrypted.
+   Cisco IOS Type 7 passwords were never meant to be secure; these passwords only protect against shoulder-surfing.  When you add users and enable passwords to your router, be sure to another Cisco IOS Type password; these are much more secure and cannot be easily decrypted.
 
 .. warning::
 

sphinx-doc/syntax.rst

@@ -0,0 +1,33 @@
+======
+syntax
+======
+
+``syntax`` is used with all configurations.  By default ``ios`` syntax 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/sfob09f02sw01.conf')
+   >>>
+
+This configuration parse explicitly reads the configuration as ``asa`` syntax:
+
+.. sourcecode:: python
+
+   >>> from ciscoconfparse import CiscoConfParse
+   >>> parse = CiscoConfParse('/tftpboot/sfob09f02fw01.conf', syntax='asa')
+   >>>
+
+``syntax`` offers a way to handle these situations:
+
+- Is the config delimited with braces or indentation?
+- Which configuration object is used to represent configuration lines?
+- These configuration objects offer the following information:
+
+  - Is a configuration line an interface?
+  - Is an interface a switchport?
+  - Is an interface administratively shutdown?
+

sphinx-doc/syntax_factory_intro.rst

@@ -0,0 +1,14 @@
+========================
+syntax and factory intro
+========================
+
+Overview
+--------
+
+When parsing configurations, vendors have some tweaks they make to the configuration.
+
+``CiscoConfParse`` has two parameters that are used to manage this.
+
+- ``syntax``
+- ``factory``
+