Merge pull request #8 from qduk/feature/docs

Adds docs for readthedocs

.pydocstyle.ini

@@ -1,7 +1,7 @@
 [pydocstyle]
 convention = google
 inherit = false
-match = (?!__init__).*\.py
+match = (?!__init__|conf).*\.py
 match-dir = (?!tests)[^\.].*
 # D212 is enabled by default in google convention, and complains if we have a docstring like:
 # """

.readthedocs.yml

@@ -0,0 +1,12 @@
+---
+version: 2
+
+sphinx:
+  builder: "html"
+  configuration: "docs/source/conf.py"
+  fail_on_warning: false
+
+python:
+  version: 3.7
+  install:
+    - requirements: "docs/requirements.txt"

README.md

@@ -34,7 +34,7 @@ Functions are grouped with like functions, such as IP or MAC address based funct
 
 # Examples
 
-While all functions come with examples in the docstrings, for quick reference of the types of problems this library intends to 
+While all functions come with examples in the docstrings, for quick reference of the types of problems this library intends to
 solve the following examples are provided.
 
 The following function will help in deploying list of VLANs and match the configuration style in a standard IOS-like configurations.
@@ -52,10 +52,10 @@ The following function will help in deploying list of VLANs and match the config
 ...         print(f"  switchport trunk allowed vlan {line}")
 ...     else:
 ...         print(f"  switchport trunk allowed vlan add {line}")
-... 
+...
   switchport trunk allowed vlan 1-3,5,6,1000,1002,1004,1006,1008,1010,1012,1014
   switchport trunk allowed vlan add 1016,1018
->>> 
+>>>
 ```
 
 You may want to compare a known password with a given encrypted password. This can help in verifying if the
@@ -111,8 +111,8 @@ issues. Functions that were known to be rewritten and their known origin.
 
 | Function | Origin |
 | -------- | ------ |
-| asn_to_int | NAPALM | 
-| is_ip | IPCal | 
+| asn_to_int | NAPALM |
+| is_ip | IPCal |
 | ip_to_bin | IPCal |
 | get_usable_range | IPCal |
 | encrypt_type7 | unknown |
@@ -141,7 +141,7 @@ The project is following Network to Code software development guidelines and are
 The project features a CLI helper based on [invoke](http://www.pyinvoke.org/) to help setup the development environment. The commands are listed below in 3 categories:
 - `dev environment`
 - `utility`
-- `testing`. 
+- `testing`.
 
 Each command can be executed with `invoke <command>`. Each command also has its own help `invoke <command> --help`
 
@@ -153,13 +153,13 @@ Each command can be executed with `invoke <command>`. Each command also has its
   rebuild          Clean the Docker image and then rebuild without using cache.
 ```
 
-### Utility 
+### Utility
 
 ```
   cli              Enter the image to perform troubleshooting or dev work.
 ```
 
-### Testing 
+### Testing
 
 ```
   bandit           Run bandit to validate basic static code security analysis.
@@ -176,3 +176,4 @@ Each command can be executed with `invoke <command>`. Each command also has its
 
 For any questions or comments, feel free to swing by the [Network to Code slack channel](https://networktocode.slack.com/) (channel #networktocode).
 Sign up [here](http://slack.networktocode.com/)
+

docs/requirements.txt

@@ -0,0 +1,4 @@
+m2r2==0.2.7
+Sphinx
+toml
+sphinx-rtd-theme

docs/source/_static/schema-page.css

@@ -0,0 +1,62 @@
+body {
+  font-family: 'Fira Sans', 'Noto Sans', 'Source Sans Pro', 'Segoe UI', Roboto, 'Lucida Sans Unicode', 'Lucida Grande', 'DejaVu Sans', sans-serif;
+}
+@media (min-width: 60em) {
+  body {
+    display: flex;
+    flex-direction: row;
+  }
+}
+#jschemer-nav {
+  min-width: 15rem;
+  padding: 1em;
+}
+.jschemer-schema {
+  border: 0.05em solid #CCC;
+  border-radius: 0.25em;
+  margin: 0.5em;
+  max-width: 60em;
+  padding: 1em;
+}
+.jschemer-schema code,
+.jschemer-schema pre {
+  background-color: rgba(27, 31, 35, 0.05);
+  border-radius: 0.1em;
+  font-size: 85%;
+  line-height: 1.5;
+}
+.jschemer-schema pre {
+  padding: 1em 0.5em;
+}
+.jschemer-schema code {
+  display: inline;
+  font-family: 'Fira Mono', 'Noto Mono', 'Source Code Pro', Consolas, 'Roboto Mono', 'Lucida Console', Monaco, 'DejaVu Sans Mono', monospace;
+  font-size: 85%;
+  line-height: inherit;
+  padding: 0.2em 0.4em;
+  word-wrap: normal;
+}
+.jschemer-schema pre > code {
+  background-color: transparent;
+  padding: 0;
+}
+.jschemer-schema h1 {
+  display: inline;
+  font-size: 1.5em;
+  vertical-align: middle;
+}
+.jschemer-schema h1 code::before {
+  content: '"';
+}
+.jschemer-schema h1 code::after {
+  content: '"';
+}
+.jschemer-schema h2 {
+  font-size: 1em;
+}
+main > .jschemer-schema > details > summary > h1 {
+  font-size: 2em;
+}
+main ul {
+  list-style: disc;
+}

docs/source/_static/theme_overrides.css

@@ -0,0 +1,13 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}

docs/source/attribution/index.rst

@@ -0,0 +1,7 @@
+############
+Attribution
+############
+
+.. mdinclude:: ../../../README.md
+   :start-line: 92
+   :end-line: 126

docs/source/conf.py

@@ -0,0 +1,93 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+# pylint: disable=W,C
+import os
+import sys
+import toml
+
+sys.path.insert(0, os.path.abspath("../.."))
+toml_dict = toml.load("../../pyproject.toml")
+
+
+# -- Project information -----------------------------------------------------
+
+project = toml_dict["tool"]["poetry"]["name"]
+copyright = f"{toml_dict['tool']['poetry']['authors'][0]}, 2021"
+author = ",".join(toml_dict["tool"]["poetry"]["authors"])
+
+# The full version, including alpha/beta/rc tags
+release = toml_dict["tool"]["poetry"]["version"]
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "m2r2"]
+
+autodoc_default_options = {
+    "members": True,
+    "show-inheritance": True,
+    "special-members": "__init__",
+    "undoc-members": True,
+}
+
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = ".rst"
+
+# The master toctree document.
+master_doc = "index"
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+html_context = {
+    "css_files": [
+        "_static/theme_overrides.css",  # override wide tables in RTD theme
+        "_static/schema-page.css",  # Add css from jschemer
+    ]
+}
+
+html_sidebars = {"**": ["globaltoc.html", "relations.html", "sourcelink.html", "searchbox.html"]}

docs/source/contributing/index.rst

@@ -0,0 +1,7 @@
+############
+Contributing
+############
+
+.. mdinclude:: ../../../README.md
+   :start-line: 131
+   :end-line: 178

docs/source/index.rst

@@ -0,0 +1,22 @@
+.. netutils documentation master file, created by
+   sphinx-quickstart on Wed May  5 01:15:43 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to netutils's documentation!
+====================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   overview/index
+   netutils/index
+   attribution/index
+   contributing/index
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`

docs/source/netutils/asn/index.rst

@@ -0,0 +1,6 @@
+*********
+BGP ASNs
+*********
+
+.. automodule:: netutils.asn
+    :members:

docs/source/netutils/configs/index.rst

@@ -0,0 +1,12 @@
+*******
+Configs
+*******
+
+.. automodule:: netutils.config.clean
+    :members:
+
+.. automodule:: netutils.config.compliance
+    :members:
+
+.. automodule:: netutils.config.parser
+    :members:

docs/source/netutils/dns/index.rst

@@ -0,0 +1,6 @@
+****
+DNS
+****
+
+.. automodule:: netutils.dns
+    :members:

docs/source/netutils/index.rst

@@ -0,0 +1,17 @@
+******************
+Netutils Functions
+******************
+
+.. toctree::
+   :maxdepth: 2
+
+   asn/index
+   configs/index
+   dns/index
+   interface/index
+   ip/index
+   mac/index
+   password/index
+   ping/index
+   route/index
+   vlan/index

docs/source/netutils/interface/index.rst

@@ -0,0 +1,6 @@
+***********
+Interfaces
+***********
+
+.. automodule:: netutils.interface
+    :members:

docs/source/netutils/ip/index.rst

@@ -0,0 +1,6 @@
+**************
+IP addresses
+**************
+
+.. automodule:: netutils.ip
+    :members:

docs/source/netutils/mac/index.rst

@@ -0,0 +1,6 @@
+**************
+MAC addresses
+**************
+
+.. automodule:: netutils.mac
+    :members:

docs/source/netutils/password/index.rst

@@ -0,0 +1,6 @@
+***********
+Passwords
+***********
+
+.. automodule:: netutils.password
+    :members:

docs/source/netutils/ping/index.rst

@@ -0,0 +1,6 @@
+******
+Ping
+******
+
+.. automodule:: netutils.ping
+    :members:

docs/source/netutils/route/index.rst

@@ -0,0 +1,6 @@
+*********
+Routing
+*********
+
+.. automodule:: netutils.route
+    :members: