Enhanced documentation

Capitains · Dec 22, 2016 · 15fa4b9 · 15fa4b9
1 parent 95962a5
commit 15fa4b9
Show file tree

Hide file tree

Showing 17 changed files with 1,434 additions and 1,119 deletions.
diff --git a/Makefile b/Makefile
@@ -3,4 +3,19 @@ svg:
 		source ./env/bin/activate; \
 		pyreverse -o png -p MyCapytain MyCapytain; \
 		pyreverse -o svg -p MyCapytain MyCapytain; \
-	)
+	)
+
+classes:
+	( \
+		source ./env/bin/activate; \
+		pyreverse -A -k -o svg -p MyCapytain_texts MyCapytain.resources.prototypes.text; \
+		pyreverse -A -k -o png -p MyCapytain_texts MyCapytain.resources.prototypes.text;
+	)
+
+move:
+	( \
+		mv classes_* doc/_static/pyreverse/;\
+		mv packages_* doc/_static/pyreverse/;\
+	)
+
+all:svg classes move
diff --git a/classes_MyCapytain.png b/classes_MyCapytain.png
diff --git a/classes_MyCapytain.svg b/classes_MyCapytain.svg
diff --git a/doc/MyCapytain.classes.rst b/doc/MyCapytain.classes.rst
@@ -53,24 +53,37 @@ Example of implementation : CTS 5
 
 :class:`MyCapytain.retrievers.cts5.CTS`
 
-.. code-block:: python
-    :linenos:
-    :caption: Retrieving a CTS API Reply
-
-    from MyCapytain.retrievers.cts5 import CTS
-
-    # We set up a retriever which communicates with an API available in Leipzig
-    retriever = CTS("http://cts.dh.uni-leipzig.de/api/cts/")
-    # We require a passage : passage is now a Passage object
-    passage = retriever.getPassage("urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1")
-    # Passage is now equal to the string content of http://cts.dh.uni-leipzig.de/api/cts/?request=GetPassage&urn=urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1
-    print(passage)
+.. literalinclude:: Retriever.py
+   :language: python
+   :linenos:
 
 
 Text and Passages
 #################
 
-Text and Passages have been divided into a lot of different object
+Description of the Hierarchy
+****************************
+
+.. figure:: _static/pyreverse/classes_MyCapytain_texts.svg
+   :alt: MyCapytain Texts Prototypes
+
+    Prototype of Texts from :module:`MyCapytain.resources.prototypes.text`. \
+    :class:`NodeId` and :class:`Exportable` are respectively from :module:`MyCapytain.common.reference` and \
+    :module:`MyCapytain.common.constants`.
+
+Objectives of Text and Passages
+*******************************
+
+Implementations : the encodings module
+**************************************
+
+Implementation example : HTTP API Passage work
+**********************************************
+
+Other Example
+*************
+
+See :ref:`MyCapytain.local`
 
 Collection
 ##########
@@ -188,35 +201,8 @@ Prototype
 Example
 *******
 
-.. code-block:: python
-    :linenos:
-    :caption: Retrieving a passage and manipulating it
-
-    from MyCapytain.resolvers.cts.api import HttpCTSResolver
-    from MyCapytain.retrievers.cts5 import CTS
-    from MyCapytain.common.utils import Mimetypes, NS
-
-    # We set up a resolver which communicates with an API available in Leipzig
-    resolver = HttpCTSResolver(CTS("http://cts.dh.uni-leipzig.de/api/cts/"))
-    # We require a passage : passage is now a Passage object
-    # This is an entry from the Smith Myth Dictionary
-    # The inner methods will resolve to the URI http://cts.dh.uni-leipzig.de/api/cts/?request=GetPassage&urn=urn:cts:pdlrefwk:viaf88890045.003.perseus-eng1:A.abaeus_1
-    # And parse it into interactive objects
-    passage = resolver.getTextualNode("urn:cts:pdlrefwk:viaf88890045.003.perseus-eng1", "A.abaeus_1")
-    # We need an export as plaintext
-    print(passage.export(
-        output=Mimetypes.PLAINTEXT
-    ))
-    """
-        Abaeus ( Ἀβαῖος ), a surname of Apollo
-         derived from the town of Abae in Phocis, where the god had a rich temple. (Hesych. s. v.
-         Ἄβαι ; Hdt. 8.33 ; Paus. 10.35.1 , &c.) [ L.S ]
-    """
-    # We want to find bibliographic information in the passage of this dictionary
-    # We need an export as LXML ETREE object to perform XPath
-    print(
-        passage.export(
-            output=Mimetypes.PYTHON.ETREE
-        ).xpath(".//tei:bibl/text()", namespaces=NS, magic_string=False)
-    )
-    ["Hdt. 8.33", "Paus. 10.35.1"]
+.. literalinclude:: Resolver.py
+   :language: python
+   :linenos:
+
+
diff --git a/doc/MyCapytain.endpoint.rst b/doc/MyCapytain.endpoint.rst
diff --git a/doc/MyCapytain.uses.rst b/doc/MyCapytain.uses.rst
@@ -20,4 +20,9 @@ HookTest
 ********
 
 `HookTest <https://github.com/Capitains/Hook/>`_ is a library and command line tools for checking resources against the Capitains Guidelines
-You'll find uses mainly in `units.py <https://github.com/Capitains/HookTest/blob/master/HookTest/units.py>`_
+You'll find uses mainly in `units.py <https://github.com/Capitains/HookTest/blob/master/HookTest/units.py>`_
+
+CLTK Corpora Converter
+**********************
+
+`Capitains Corpora Converter <https://github.com/Capitains/Hook/>`_ Converts CapiTainS-based Repository ( http://capitains.github.io ) to JSON for CLTK
diff --git a/doc/Resolver.py b/doc/Resolver.py
@@ -0,0 +1,28 @@
+from MyCapytain.resolvers.cts.api import HttpCTSResolver
+from MyCapytain.retrievers.cts5 import CTS
+from MyCapytain.common.constants import Mimetypes, NS
+
+# We set up a resolver which communicates with an API available in Leipzig
+resolver = HttpCTSResolver(CTS("http://cts.dh.uni-leipzig.de/api/cts/"))
+# We require a passage : passage is now a Passage object
+# This is an entry from the Smith Myth Dictionary
+# The inner methods will resolve to the URI http://cts.dh.uni-leipzig.de/api/cts/?request=GetPassage&urn=urn:cts:pdlrefwk:viaf88890045.003.perseus-eng1:A.abaeus_1
+# And parse it into interactive objects
+passage = resolver.getTextualNode("urn:cts:pdlrefwk:viaf88890045.003.perseus-eng1", "A.abaeus_1")
+# We need an export as plaintext
+print(passage.export(
+    output=Mimetypes.PLAINTEXT
+))
+"""
+    Abaeus ( Ἀβαῖος ), a surname of Apollo
+     derived from the town of Abae in Phocis, where the god had a rich temple. (Hesych. s. v.
+     Ἄβαι ; Hdt. 8.33 ; Paus. 10.35.1 , &c.) [ L.S ]
+"""
+# We want to find bibliographic information in the passage of this dictionary
+# We need an export as LXML ETREE object to perform XPath
+print(
+    passage.export(
+        output=Mimetypes.PYTHON.ETREE
+    ).xpath(".//tei:bibl/text()", namespaces=NS, magic_string=False)
+)
+["Hdt. 8.33", "Paus. 10.35.1"]
diff --git a/doc/Retriever.py b/doc/Retriever.py
@@ -0,0 +1,24 @@
+from MyCapytain.retrievers.cts5 import CTS
+
+# We set up a retriever which communicates with an API available in Leipzig
+retriever = CTS("http://cts.dh.uni-leipzig.de/api/cts/")
+# We require a passage : passage is now a Passage object
+passage = retriever.getPassage("urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1")
+# Passage is now equal to the string content of http://cts.dh.uni-leipzig.de/api/cts/?request=GetPassage&urn=urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1
+print(passage)
+
+"""
+<GetPassage><request><requestName>GetPassage</requestName><requestUrn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1</requestUrn></request>
+<reply><urn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1</urn><passage><TEI>
+<text n="urn:cts:latinLit:phi1294.phi002.perseus-lat2" xml:id="stoa0045.stoa0"><body>
+<div type="edition" n="urn:cts:latinLit:phi1294.phi002.perseus-lat2" xml:lang="lat">
+<div type="textpart" subtype="book" n="1"><div type="textpart" subtype="poem" n="1">
+<head>I</head>
+<l n="1">Hic est quem legis ille, quem requiris, </l>
+<l n="2">Toto notus in orbe Martialis </l>
+<l n="3">Argutis epigrammaton libellis: <pb/></l>
+<l n="4">Cui, lector studiose, quod dedisti </l>
+<l n="5">Viventi decus atque sentienti, </l>
+<l n="6">Rari post cineres habent poetae. </l>
+</div></div></div></body></text></TEI></passage></reply>
+"""
diff --git a/doc/_static/pyreverse/classes_MyCapytain.png b/doc/_static/pyreverse/classes_MyCapytain.png