Merge pull request #8 from psycofdj/more_documentation

documentation

Makefile

@@ -2,6 +2,8 @@ SOURCES=$(shell find . -name '*.py' | grep -v test_)
 SOURCEDIRS=$(shell find . -name '*.py' | grep -v test | xargs dirname | sort -u)
 TESTS=$(shell find . -name 'test_*.py')
 
+all: cov covdoc cov pylint dist
+
 .doc-built: $(SOURCES) $(TESTS) Makefile
 	@make -s -C docs html
 	@touch $@
@@ -17,26 +19,30 @@ check: $(SOURCES)
 	@./devtools/coverage.sh
 	@touch $@
 
+.dist-built: $(SOURCES) Makefile setup.py setup.cfg
+	@./setup.py sdist
+	@touch $@
+
 .pylint-built: $(SOURCES) Makefile
 	@mkdir -p build/pylint/
 	@./devtools/xtdlint.py --rcfile=.pylintrc -j4 xtd -f html > build/pylint/index.html || true
+	@./devtools/xtdlint.py --rcfile=.pylintrc --reports=no -j4 xtd -f text || true
 	@touch $@
 
 .cov-report-built: .cov-built
 	@coverage3 html -d build/coverage
 	@touch $@
 
-all: cov covdoc cov pylint
-
 cov: .cov-built .cov-report-built
 covdoc: .covdoc-built
 doc: .doc-built
 pylint: .pylint-built
+dist: .dist-built
 
 show-cov: .cov-report-built
 	@sensible-browser build/coverage/index.html &
 show-doc: .doc-built
-	@sensible-browser build/docs/html/index.html &
+	@sensible-browser build/docs/html/xtd.html &
 show-covdoc: .covdoc-built
 	@sensible-browser build/docs/coverage/python.txt &
 show-pylint: .pylint-built
@@ -45,4 +51,4 @@ show-pylint: .pylint-built
 show: all show-doc show-cov show-covdoc show-pylint
 
 clean:
-	@rm -rf xtd.egg-info dist build .cov-built .cov-report-built .coverage  .doc-built .covdoc-built
+	@rm -rf .dist-built xtd.egg-info dist build .cov-built .cov-report-built .coverage  .doc-built .covdoc-built

docs/Makefile

@@ -55,15 +55,22 @@ clean:
 
 .PHONY: api
 api:
-	@sphinx-apidoc -M -f -o . ../xtd/ ../xtd/test/
-	@rm -f modules.rst
+	sphinx-apidoc -d 999 -e -M -f -o . ../xtd/ ../xtd/test/
+	rm -f modules.rst
 
 .PHONY: html
 html: api
 	$(SPHINXBUILD) -qW -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+
+.PHONY: html-only
+html-only:
+	$(SPHINXBUILD) -qW -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
 .PHONY: dirhtml
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml

docs/_static/base.py

@@ -0,0 +1,17 @@
+import xtd.core.application
+
+class MergeApplication(xtd.core.application.Application):
+  def __init__(self):
+    super().__init__("MyAppName")
+    # register input options
+
+  def initialize(self):
+    super().initialize()
+    # do some initialization suff
+
+  def process(self):
+    l_exitCode = 0
+    # do some stuff
+    return l_exitCode, True
+
+MergeApplication().execute()

docs/_static/design.graphml

@@ -0,0 +1,222 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:y="http://www.yworks.com/xml/graphml" xmlns:yed="http://www.yworks.com/xml/yed/3" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://www.yworks.com/xml/schema/graphml/1.1/ygraphml.xsd">
+  <!--Created by yEd 3.12.2-->
+  <key for="graphml" id="d0" yfiles.type="resources"/>
+  <key for="port" id="d1" yfiles.type="portgraphics"/>
+  <key for="port" id="d2" yfiles.type="portgeometry"/>
+  <key for="port" id="d3" yfiles.type="portuserdata"/>
+  <key attr.name="url" attr.type="string" for="node" id="d4"/>
+  <key attr.name="description" attr.type="string" for="node" id="d5"/>
+  <key for="node" id="d6" yfiles.type="nodegraphics"/>
+  <key attr.name="Description" attr.type="string" for="graph" id="d7"/>
+  <key attr.name="url" attr.type="string" for="edge" id="d8"/>
+  <key attr.name="description" attr.type="string" for="edge" id="d9"/>
+  <key for="edge" id="d10" yfiles.type="edgegraphics"/>
+  <graph edgedefault="directed" id="G">
+    <data key="d7"/>
+    <node id="n0">
+      <data key="d5"/>
+      <data key="d6">
+        <y:ShapeNode>
+          <y:Geometry height="44.0" width="193.0" x="122.0" y="324.0"/>
+          <y:Fill color="#FFCC00" transparent="false"/>
+          <y:BorderStyle color="#000000" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" modelName="custom" textColor="#000000" visible="true" width="100.263671875" x="46.3681640625" y="6.03125">core.application
+Application<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+          <y:Shape type="rectangle"/>
+        </y:ShapeNode>
+      </data>
+    </node>
+    <node id="n1">
+      <data key="d5"/>
+      <data key="d6">
+        <y:ShapeNode>
+          <y:Geometry height="44.0" width="193.0" x="440.0" y="244.0"/>
+          <y:Fill color="#FFCC00" transparent="false"/>
+          <y:BorderStyle color="#000000" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="70.791015625" x="61.1044921875" y="13.015625">core.config<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+          <y:Shape type="rectangle"/>
+        </y:ShapeNode>
+      </data>
+    </node>
+    <node id="n2">
+      <data key="d5"/>
+      <data key="d6">
+        <y:ShapeNode>
+          <y:Geometry height="44.0" width="193.0" x="440.0" y="300.0"/>
+          <y:Fill color="#FFCC00" transparent="false"/>
+          <y:BorderStyle color="#000000" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="72.296875" x="60.3515625" y="13.015625">core.logger<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+          <y:Shape type="rectangle"/>
+        </y:ShapeNode>
+      </data>
+    </node>
+    <node id="n3">
+      <data key="d5"/>
+      <data key="d6">
+        <y:ShapeNode>
+          <y:Geometry height="44.0" width="193.0" x="440.0" y="356.0"/>
+          <y:Fill color="#FFCC00" transparent="false"/>
+          <y:BorderStyle color="#000000" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="73.017578125" x="59.9912109375" y="13.015625">core.param<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+          <y:Shape type="rectangle"/>
+        </y:ShapeNode>
+      </data>
+    </node>
+    <node id="n4">
+      <data key="d5"/>
+      <data key="d6">
+        <y:ShapeNode>
+          <y:Geometry height="44.0" width="193.0" x="440.0" y="412.0"/>
+          <y:Fill color="#FFCC00" transparent="false"/>
+          <y:BorderStyle color="#000000" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="57.0859375" x="67.95703125" y="13.015625">core.stat<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+          <y:Shape type="rectangle"/>
+        </y:ShapeNode>
+      </data>
+    </node>
+    <node id="n5">
+      <data key="d5"/>
+      <data key="d6">
+        <y:ShapeNode>
+          <y:Geometry height="44.0" width="193.0" x="122.0" y="565.0"/>
+          <y:Fill color="#FFCC00" transparent="false"/>
+          <y:BorderStyle color="#000000" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" modelName="custom" textColor="#000000" visible="true" width="124.603515625" x="34.1982421875" y="6.03125">core.network.server
+Application<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+          <y:Shape type="rectangle"/>
+        </y:ShapeNode>
+      </data>
+    </node>
+    <node id="n6">
+      <data key="d5"/>
+      <data key="d6">
+        <y:ShapeNode>
+          <y:Geometry height="44.0" width="159.0" x="-110.0" y="565.0"/>
+          <y:Fill color="#FFCC00" transparent="false"/>
+          <y:BorderStyle color="#000000" type="line" width="1.0"/>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" modelName="custom" textColor="#000000" visible="true" width="119.576171875" x="19.7119140625" y="6.03125">core.network.client
+AsyncClient<y:LabelModel>
+              <y:SmartNodeLabelModel distance="4.0"/>
+            </y:LabelModel>
+            <y:ModelParameter>
+              <y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
+            </y:ModelParameter>
+          </y:NodeLabel>
+          <y:Shape type="rectangle"/>
+        </y:ShapeNode>
+      </data>
+    </node>
+    <edge id="e0" source="n5" target="n0">
+      <data key="d8"/>
+      <data key="d9"/>
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
+          <y:LineStyle color="#000000" type="line" width="1.0"/>
+          <y:Arrows source="none" target="white_delta"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="e1" source="n0" target="n1">
+      <data key="d8"/>
+      <data key="d9"/>
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="96.5" sy="0.0" tx="-96.5" ty="0.0">
+            <y:Point x="378.0" y="346.0"/>
+            <y:Point x="378.0" y="266.0"/>
+          </y:Path>
+          <y:LineStyle color="#000000" type="dashed" width="1.0"/>
+          <y:Arrows source="none" target="plain"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="e2" source="n0" target="n2">
+      <data key="d8"/>
+      <data key="d9"/>
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="96.5" sy="0.0" tx="-96.5" ty="0.0">
+            <y:Point x="378.0" y="346.0"/>
+            <y:Point x="378.0" y="322.0"/>
+          </y:Path>
+          <y:LineStyle color="#000000" type="dashed" width="1.0"/>
+          <y:Arrows source="none" target="plain"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="e3" source="n0" target="n3">
+      <data key="d8"/>
+      <data key="d9"/>
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="96.5" sy="0.0" tx="-96.5" ty="0.0">
+            <y:Point x="378.0" y="346.0"/>
+            <y:Point x="378.0" y="378.0"/>
+          </y:Path>
+          <y:LineStyle color="#000000" type="dashed" width="1.0"/>
+          <y:Arrows source="none" target="plain"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+    <edge id="e4" source="n0" target="n4">
+      <data key="d8"/>
+      <data key="d9"/>
+      <data key="d10">
+        <y:PolyLineEdge>
+          <y:Path sx="96.5" sy="0.0" tx="-96.5" ty="0.0">
+            <y:Point x="378.0" y="346.0"/>
+            <y:Point x="378.0" y="434.0"/>
+          </y:Path>
+          <y:LineStyle color="#000000" type="dashed" width="1.0"/>
+          <y:Arrows source="none" target="plain"/>
+          <y:BendStyle smoothed="false"/>
+        </y:PolyLineEdge>
+      </data>
+    </edge>
+  </graph>
+  <data key="d0">
+    <y:Resources/>
+  </data>
+</graphml>

docs/_static/options.json

@@ -0,0 +1,12 @@
+{
+  "log" : {
+    "config" : {},
+    "override" : {
+      "loggers" : {
+        "root" : {
+          "level" : 10
+        }
+      }
+    }
+  }
+}

docs/_static/options.py

@@ -0,0 +1,31 @@
+import xtd.core.application
+import xtd.core.config
+import xtd.core.logger
+import xtd.core.config.checkers
+
+class MergeApplication(xtd.core.application.Application):
+  def __init__(self):
+    super().__init__("MergeApplication")
+
+    self.m_config.register_section("input", "Input settings", [{
+      "name"        : "directory",
+      "default"     : "./work_to_do/",
+      "description" : "Read input files from given directory",
+      "checks"      : xtd.core.config.checkers.is_dir(p_write=True)
+    },{
+      "name"        : "count",
+      "default"     : 1,
+      "description" : "Number of file to read in directory",
+      "checks"      : xtd.core.config.checkers.is_int(p_min=0)
+    }])
+
+    self.m_config.register_section("output", "Output settings", [{
+      "name"        : "file",
+      "description" : "Destination file",
+      "checks"      : xtd.core.config.checkers.is_file(p_write=True)
+    }])
+
+
+if __name__ == "__main__":
+  l_app = MergeApplication()
+  l_app.execute()

docs/_static/options_output.txt

@@ -0,0 +1,34 @@
+$ python3 test.py --help
+
+Usage: MergeApplication [options]
+
+Options:
+  --help                       show this help message and exit
+
+  General Settings:
+    --config-file=ARG          use FILE as configuration file [default:MergeApplication/MergeApplication.json]
+
+  Input settings:
+    --input-directory=ARG      Read input files from given directory [default:./work_to_do/]
+    --input-count=ARG          Number of file to read in directory [default:1]
+
+  Logging Settings:
+    --log-config=ARG           Logging configuration [default:{}]
+    --log-override=ARG         override part of logging configuration [default:{}]
+
+  Output settings:
+    --output-file              Destination file [default:False]
+
+  Persitent Param Settings:
+    --param-directory=ARG      Destination directory for admin persistent parameters [default:/tmp/snmp/MergeApplication/admin]
+
+  Stats Settings:
+    --stat-writters=ARG        Enabled given stat output writter. Possibles values :
+                               * disk : write counters to --stat-disk-directory path each --stat-disk-interval seconds
+                               * http : post counters in json format to --stat-http-url url each --stat-http-interval seconds
+                               Can specify a comma separated combinaison of theses values
+                               [default:['disk']]
+    --stat-disk-directory=ARG  Destination directory for counter disk writter [default:/tmp/snmp/MergeApplication/stat/]
+    --stat-disk-interval=ARG   Interval in second between two disk outputs [default:50]
+    --stat-http-url=ARG        Destination POST url for http stat writter [default:http://localhost/counter]
+    --stat-http-interval=ARG   Interval in second between two http outputs [default:50]