Improve documentation (#2661)

Integrate .md files into official documentation
See: https://stackoverflow.com/questions/46278683/include-my-markdown-readme-into-sphinx/68005314#68005314

12 files changed, 37 insertions, 14 deletions

diff --git a/Makefile.am b/Makefile.am
index 5ac5bf475..70ee2fc0b 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -12,18 +12,22 @@ EXTRA_DIST = README.md README.fuzzer.md CHANGELOG.md CONTRIBUTING.md \
 	autogen.sh wireshark windows utils packages dga \
 	influxdb/Makefile.in influxdb/metric_anomaly.c influxdb/README.txt \
 	rrdtool/Makefile.in rrdtool/README.txt rrdtool/rrd_anomaly.c rrdtool/rrd_similarity.c \
-	doc/requirements.txt doc/monitoring.md doc/conf.py doc/flow_risks.rst doc/protocols.rst doc/guide/nDPI_QuickStartGuide.pages \
+	doc/requirements.txt doc/conf.py doc/flow_risks.rst doc/protocols.rst doc/guide/nDPI_QuickStartGuide.pages \
 		doc/guide/nDPI_QuickStartGuide.pdf doc/img/logo.png doc/index.rst \
-		doc/Makefile doc/what_is_ndpi.rst doc/FAQ.md doc/configuration_parameters.md \
-		doc/library_initialization.md \
+		doc/Makefile doc/what_is_ndpi.rst \
+		doc/FAQ.md doc/include_FAQ.rst \
+		doc/configuration_parameters.md doc/include_configuration_parameters.rst \
+		doc/library_initialization.md doc/include_library_initialization.rst \
+		doc/monitoring.md doc/include_monitoring.rst \
+		doc/_static/custom.css \
 	python/DEV_GUIDE.md python/dev_requirements.txt python/ndpi_example.py python/ndpi/__init__.py \
 		python/ndpi/ndpi_build.py python/ndpi/ndpi.py python/README.md \
 		python/requirements.txt python/setup.py python/tests.py \
 	lists/100_malware.list \
-	lists/107_gambling.list \
-	lists/107_gambling_custom.list \
-	lists/public_suffix_list.dat \
-	lists/README.md \
+		lists/107_gambling.list \
+		lists/107_gambling_custom.list \
+		lists/public_suffix_list.dat \
+		lists/README.md \
 	sonar-project.properties .github .ci-ignore
 
 doc:
diff --git a/doc/FAQ.md b/doc/FAQ.md
index 75e568de6..41efa0843 100644
--- a/doc/FAQ.md
+++ b/doc/FAQ.md
@@ -1,6 +1,7 @@
+
 # FAQ
 
-From https://www.ntop.org/ndpi/ndpi-internals-and-frequent-questions/
+From [blog post](https://www.ntop.org/ndpi/ndpi-internals-and-frequent-questions/)
 
 **Q**: How nDPI implements protocol detection?\
 **A**: nDPI includes a list of protocol dissectors (364 as of today) that are able to dissect protocols such as WhatsApp or TLS. As soon as a new flow is submitted to nDPI, the library applies in sequence dissectors that can potentially match the protocols (i.e. telnet is a TCP-based protocol, and it will not be considered for UDP flows). We start from the dissector that can most probably match using the port number. This means for traffic on TCP/22 nDPI will start with the SSH dissectors and if not matching continue with the others. Dissection completes as soon as a protocol matches or when none of them matched and in this case the flow will be labelled as Unknown.
diff --git a/doc/_static/custom.css b/doc/_static/custom.css
new file mode 100644
index 000000000..0b570a74a
--- /dev/null
+++ b/doc/_static/custom.css
@@ -0,0 +1,3 @@
+.wy-nav-content {
+    max-width: 75% !important;
+}
diff --git a/doc/conf.py b/doc/conf.py
index 9650652f2..039359bb7 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -22,7 +22,8 @@ sys.path.append( "breathe/" )
 extensions = [
     'sphinx.ext.intersphinx',
     'breathe',
-    'exhale'
+    'exhale',
+    'myst_parser'
 ]
 
 # Workaround for platforms where swaggerdoc is not available
@@ -49,7 +50,7 @@ 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': 'restructuredtext', '.md': 'restructuredtext'}
 #source_suffix = '.rst'
 
 # The encoding of source files.
@@ -152,7 +153,7 @@ html_logo = "img/logo.png"
 # 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_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -298,7 +299,8 @@ texinfo_documents = [
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
 
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
 
 def setup(app):
     app.add_css_file('css/ntop.css')
+    app.add_css_file('custom.css')
diff --git a/doc/configuration_parameters.md b/doc/configuration_parameters.md
index 1f455c3f3..f42ba0d59 100644
--- a/doc/configuration_parameters.md
+++ b/doc/configuration_parameters.md
@@ -1,7 +1,7 @@
 
 # Configuration knobs
 
-TODO
+List of the supported configuration options:
 
 | Protocol     | Parameter                                 | Default value | Min value | Max value | Description | Notes  |
 | ------       | ------                                    | ------        | ------    | ------    | ------      | ------ |
diff --git a/doc/include_FAQ.rst b/doc/include_FAQ.rst
new file mode 100644
index 000000000..b384b6997
--- /dev/null
+++ b/doc/include_FAQ.rst
@@ -0,0 +1,2 @@
+.. include:: FAQ.md
+   :parser: myst_parser.sphinx_
diff --git a/doc/include_configuration_parameters.rst b/doc/include_configuration_parameters.rst
new file mode 100644
index 000000000..0ef417fbe
--- /dev/null
+++ b/doc/include_configuration_parameters.rst
@@ -0,0 +1,2 @@
+.. include:: configuration_parameters.md
+   :parser: myst_parser.sphinx_
diff --git a/doc/include_library_initialization.rst b/doc/include_library_initialization.rst
new file mode 100644
index 000000000..2b126e98b
--- /dev/null
+++ b/doc/include_library_initialization.rst
@@ -0,0 +1,2 @@
+.. include:: library_initialization.md
+   :parser: myst_parser.sphinx_
diff --git a/doc/include_monitoring.rst b/doc/include_monitoring.rst
new file mode 100644
index 000000000..ac4332214
--- /dev/null
+++ b/doc/include_monitoring.rst
@@ -0,0 +1,2 @@
+.. include:: monitoring.md
+   :parser: myst_parser.sphinx_
diff --git a/doc/index.rst b/doc/index.rst
index 1b1118d5b..32a8f30e3 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -8,6 +8,7 @@ nDPI is an open source DPI (Deep Packet Inspection) toolkit for traffic analysis
    :caption: User's Guide
 
    what_is_ndpi
+   include_FAQ
 
 .. toctree::
    :maxdepth: 2
@@ -16,6 +17,9 @@ nDPI is an open source DPI (Deep Packet Inspection) toolkit for traffic analysis
    api/library_root
    protocols
    flow_risks
+   include_configuration_parameters
+   include_library_initialization
+   include_monitoring
 
 .. toctree::
    :caption: Other Products
diff --git a/doc/library_initialization.md b/doc/library_initialization.md
index f70051aa9..491d00c93 100644
--- a/doc/library_initialization.md
+++ b/doc/library_initialization.md
@@ -1,5 +1,5 @@
 
-
+# Library Initialization
 
 A simple, common example
 
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 83160cdcf..0a8c61d0f 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -2,3 +2,4 @@ breathe
 exhale
 sphinx-rtd-theme
 sphinxcontrib-swaggerdoc
+myst_parser