Update documentation and dependencies to build Sphinx documentation

Author: stevelorenz

.travis.yml

@@ -173,18 +173,7 @@ def do_DELETE(self):
 
 
 class APPContainerManager:
-    """Manager for application containers (sibling containers) deployed on
-    Mininet hosts.
-
-    - To make is simple. It uses docker-py APIs to manage internal containers
-      from host system.
-
-    - Internal methods (starts with an underscore) should be documented after
-      tests and before stable releases.
-
-    Ref:
-        [1] https://docker-py.readthedocs.io/en/stable/containers.html
-    """
+    """Manager for application containers (sibling containers) deployed on Mininet hosts."""
 
     reserved_docker_args = [
         "init",
@@ -220,8 +209,7 @@ class APPContainerManager:
     def __init__(self, net: Mininet):
         """Init the APPContainerManager.
 
-        :param net (Mininet): The mininet object, used to manage hosts via
-        Mininet's API.
+        :param net (Mininet): The mininet object, used to manage hosts via Mininet's API.
         """
         self.net = net
         self.dclt = docker.from_env()

README.md

@@ -12,20 +12,24 @@
 # 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.
 #
+
+import datetime
 import os
 import sys
-sys.path.insert(0, os.path.abspath('..'))
+
+sys.path.insert(0, os.path.abspath(".."))
 
 # -- Project information -----------------------------------------------------
 
 project = "ComNetsEmu"
-copyright = "2019, The Deutsche Telekom Chair of Communication Networks"
+year = datetime.datetime.now().year
+copyright = "%d The Deutsche Telekom Chair of Communication Networks" % year
 author = "Zuo Xiang"
 
 # The short X.Y version
-version = "v0.1"
+version = "v0.3"
 # The full version, including alpha/beta/rc tags
-release = "v0.1.5"
+release = "v0.3.0"
 
 # -- General configuration ---------------------------------------------------
 
@@ -37,28 +41,20 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc', 'sphinxcontrib.apidoc',
-    'sphinx.ext.autosectionlabel', 'sphinx.ext.doctest', 'recommonmark',
-    'sphinxcontrib.napoleon'
+    # Use builtin extensions in sphinx
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.doctest",
+    "sphinx.ext.napoleon",
+    # Add markdown support
+    "myst_parser",
 ]
 
-# Mock calls to external libraries
-autodoc_mock_imports = ["pytest"]
-
-# API doc parameters
-apidoc_module_dir = '../comnetsemu/'
-apidoc_output_dir = 'api'
-apidoc_excluded_paths = ['test']
-apidoc_separate_modules = True
-apidoc_module_first = True
-apidoc_extra_args = ['-H', 'ComNetsEmu API', '-d', '6']
-autoclass_content = "both"
-
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -70,23 +66,27 @@
 # 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 = ['build', 'Thumbs.db', '.DS_Store', 'comparison.md']
+exclude_patterns = ["build", "Thumbs.db", ".DS_Store", "comparison.md"]
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = None
+pygments_style = "sphinx"
 
 # -- 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"
+html_theme = "alabaster"
+
 
 # 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 = {}
+html_theme_options = {
+    "description": "A virtual emulator/testbed designed for the book: Computing in Communication Networks: From Theory to Practice",
+    "fixed_sidebar": True,
+}
 
 # 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,
@@ -106,23 +106,20 @@
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'ComNetsEmudoc'
+htmlhelp_basename = "ComNetsEmudoc"
 
 # -- Options for LaTeX output ------------------------------------------------
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
@@ -132,25 +129,30 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'ComNetsEmu.tex', 'ComNetsEmu Documentation', 'Zuo Xiang',
-     'manual'),
+    (master_doc, "ComNetsEmu.tex", "ComNetsEmu Documentation", "Zuo Xiang", "manual"),
 ]
 
 # -- Options for manual page output ------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, 'comnetsemu', 'ComNetsEmu Documentation', [author],
-              1)]
+man_pages = [(master_doc, "comnetsemu", "ComNetsEmu Documentation", [author], 1)]
 
 # -- Options for Texinfo output ----------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'ComNetsEmu', 'ComNetsEmu Documentation', author,
-     'ComNetsEmu', 'One line description of project.', 'Miscellaneous'),
+    (
+        master_doc,
+        "ComNetsEmu",
+        "ComNetsEmu Documentation",
+        author,
+        "ComNetsEmu",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
 ]
 
 # -- Options for Epub output -------------------------------------------------
@@ -168,4 +170,4 @@
 # epub_uid = ''
 
 # A list of files that should not be packed into the epub file.
-epub_exclude_files = ['search.html']
+epub_exclude_files = ["search.html"]

comnetsemu/net.py

@@ -1,30 +1,36 @@
-# FAQ #
+# FAQ
 
-## General Questions ##
+## General Questions
 
-##### Why not the vanilla Mininet ?
+### Why not the vanilla Mininet ?
 
-Default Mininet (the latest version) does not support running Docker containers applications directly inside Mininet Host with sufficient network isolation.
-ComNetsEmu adds a new node type: DockerHost to deploy internal Docker application containers.
+Default Mininet (the latest version) does not support running Docker containers
+applications directly inside Mininet Host with sufficient network isolation.
+ComNetsEmu adds a new node type: DockerHost to deploy internal Docker
+application containers.
 
-##### Why not Containernet ?
+### Why not Containernet ?
 
 Containernet did a fork (hold all source codes of Mininet in its own Repo) of the Mininet.
 New features and fixes from upstream Mininet can not be **merged** into Containernet **directly**.
 ComNetsEmu is only an extension of the upstream Mininet:
 
 -   Mininet's Python modules are installed with its built-in installer and only used as **dependencies**.
 
--   ComNetsEmu's Python modules only create sub-classes of **essential and minimal** classes of Mininet to add its
-    features. So Mininet must be installed before installing ComNetsEmu.
+-   ComNetsEmu's Python modules only create sub-classes of **essential and
+	minimal** classes of Mininet to add its features.
+	So Mininet must be installed before installing ComNetsEmu.
 
--   With this development profile, upstream's commits can be updated easily by running the installer's update function.
+-   With this development profile, upstream's commits can be updated easily by
+	running the installer's update function.
 
--   ComNetsEmu tries its best to keep the comparability with upstream Mininet. All examples, CLI commands of Mininet
-    should also work on ComNetsEmu.
+-   ComNetsEmu tries its best to keep the comparability with upstream Mininet.
+	All examples, CLI commands of Mininet should also work on ComNetsEmu.
 
-##### Why not Kubernetes(K8s)?
+### Why not Kubernetes(K8s)?
 
 For teaching and emulation on a single laptop, K8s is too heavy and complex.
 ComNetsEmu can emulate typical K8s setup with more lightweight virtualisation.
-And thanks to Mininet, all links on the data plane can be configured with different bandwidth, link losses or transport delay (Use Linux TC utility). It is great for teaching.
+And thanks to Mininet, all links on the data plane can be configured with
+different bandwidth, link losses or transport delay (Use Linux TC utility).
+It is great for teaching.

doc/conf.py

@@ -3,20 +3,26 @@
    but it should at least contain the root `toctree` directive.
 
 ComNetsEmu's Documentation!
-==========================
+===========================
 
-ComNetsEmu is a tested and network emulator designed for the NFV/SDN teaching book "Computing in Communication Networks: From Theory to Practice".
+A virtual emulator/testbed designed for the book:
+`Computing in Communication Networks: From Theory to
+Practice <https://www.amazon.com/Computing-Communication-Networks-Theory-Practice-ebook/dp/B088ZS597R>`_
 
-The design focus on emulating all examples and applications on a single computer, e.g. on a single laptop.
-ComNetsEmu extends the famous `Mininet <http://mininet.org/>`_ emulator to support better emulation of versatile NFV/SDN network **applications**.
+Check the `README <https://github.com/stevelorenz/comnetsemu/blob/master/README.md>`_ for project description.
+
+This online page is mainly for ComNetsEmu API documentation.
 
 .. toctree::
     :maxdepth: 2
 
     api/modules
-    dependencies
+    installation
+
     faq
     ref_links
+    roadmap
+    vm_setup_issues
 
 
 Indices and tables