Modified instance.rst

docs/modules/instance.rst

@@ -1,22 +1,41 @@
 instance
 ========
 
-.. warning::
+The Instance Document uses the concepts created in the taxonomy to tag the
+numbers to be reported, giving them meaning and structure.
+Thus, the instance document embodies the actual business report, for example,
+the annual financial statement.
 
-   !!! This documentation is currently under development !!!
+There are two different types of instance documents:
+the classic XBRL instance document (XML) and the iXBRL instance document (HTML).
+Both types are based on the same elements but are written in different file types.
+
+The core elements of every Instance document are the Facts. A **fact** is a
+number (150000) combined with a **context** (from Jan-Dec 2020 for company xyz),
+a **unit** (USD) and tagged with a **concept** from the taxonomy (us-gaap_Revenue).
+The Context defines the time frame and the company to which the fact belongs.
+
+
+Parse functions
+---------------
+
+.. automodule:: xbrl.instance
+
+    .. automethod:: xbrl.instance.parse_xbrl_url
+    .. automethod:: xbrl.instance.parse_xbrl
+    .. automethod:: xbrl.instance.parse_ixbrl_url
+    .. automethod:: xbrl.instance.parse_ixbrl
+
+Classes
+--------------
 
-XbrlParser
-----------
 .. autoclass:: xbrl.instance::XbrlParser
     :members:
     :inherited-members:
 
     .. automethod:: __init__
 
 
-XbrlInstance
-------------
-
 .. autoclass:: xbrl.instance::XbrlInstance
     :members:
     :inherited-members:

docs/modules/taxonomy.rst

@@ -1,12 +1,45 @@
 taxonomy
 ========
+Since there is a large number of financial information with different
+accounting systems (us-gaap, ifrs…), a common language framework must
+be established prior to the data transfer. In the XBRL context, this
+common language framework is called a Taxonomy. The taxonomy defines
+a list of concepts that can then be used in the instance document to
+tag certain numbers and ensures the integrity and syntactic correctness
+of the data.
+The taxonomy schema is the heart of the taxonomy and defines the
+concepts of the taxonomy. The concepts will later be used by the
+creator of a financial report to tag certain numbers.
+A Taxonomy schema defines the reportable concepts and links the
+linkbases to describe the relationships between the concepts.
+Taxonomy schemas can import multiple different taxonomy schemas.
 
-.. warning::
+The current Taxonomy Schema can override the extended schemas in the following way:
 
-   !!! This documentation is currently under development !!!
+1. Addition of new concepts:
+New concepts are added in this TaxonomySchema to extend the concepts declared in the base Taxonomy schemas
 
+2. Addition of resources:
+The Label Linkbase of this taxonomy can add new labels to existing concepts from the base taxonomy
 
-TaxonomySchema
+3. Overriding of relationships:
+All Linkbases of this taxonomy can override i.e the order of concepts in a definition linkbase
+
+4. Overriding of resources:
+The Label Linkbase of this taxonomy can override the labels of the base taxonomy!
+
+read more at: https://manusimidt.dev/2021-07/xbrl-explained
+
+Parse functions
+---------------
+
+.. automodule:: xbrl.taxonomy
+
+
+    .. automethod:: xbrl.taxonomy.parse_taxonomy_url
+    .. automethod:: xbrl.taxonomy.parse_taxonomy
+
+Classes
 --------------
 
 .. autoclass:: xbrl.taxonomy::Concept

xbrl/instance.py

@@ -266,14 +266,15 @@ def __str__(self) -> str:
 
 def parse_xbrl_url(instance_url: str, cache: HttpCache) -> XbrlInstance:
     """
-    Parses a instance file with it's taxonomy
+    Parses a instance file with it's taxonomy. This function will check, if the instance file is already
+    in the cache and load it from there based on the instance_url.
+    For EDGAR submissions: Before calling this method; extract the enclosure and copy the files to the cache.
+    i.e. Use CacheHelper.extract_edgar_enclosure()
+
     :param instance_url: url to the instance file (on the internet)
     :param cache: HttpCache instance
-    This function will check, if the instance file is already in the cache and load it from there based on the
-    instance_url.
-    For EDGAR submissions: Before calling this method; extract the enclosure and copy the files to the cache.
-        i.e. Use CacheHelper.extract_edgar_enclosure()
-    :return:
+
+    :return: parsed XbrlInstance object containing all facts with additional information
     """
     instance_path: str = cache.cache_file(instance_url)
     return parse_xbrl(instance_path, cache, instance_url)
@@ -282,12 +283,13 @@ def parse_xbrl_url(instance_url: str, cache: HttpCache) -> XbrlInstance:
 def parse_xbrl(instance_path: str, cache: HttpCache, instance_url: str or None = None) -> XbrlInstance:
     """
     Parses a instance file with it's taxonomy
+
     :param instance_path: url to the instance file (on the internet)
     :param cache: HttpCache instance
     :param instance_url: optional url to the instance file. Is sometimes necessary if the xbrl filings have their own
-    extension taxonomy. If i.e. a submission from the sec is parsed, the instance file might reference the taxonomy schema
-    with a relative path (since it is in the same directory as the instance file) schemaRef="./aapl-20211231.xsd"
-    :return:
+        extension taxonomy. If i.e. a submission from the sec is parsed, the instance file might reference the taxonomy schema
+        with a relative path (since it is in the same directory as the instance file) schemaRef="./aapl-20211231.xsd"
+    :return: parsed XbrlInstance object containing all facts with additional information
     """
     root: ET.Element = parse_file(instance_path).getroot()
     # get the link to the taxonomy schema and parse it
@@ -354,13 +356,10 @@ def parse_xbrl(instance_path: str, cache: HttpCache, instance_url: str or None =
 def parse_ixbrl_url(instance_url: str, cache: HttpCache) -> XbrlInstance:
     """
     Parses a inline XBRL (iXBRL) instance file.
+
     :param cache: HttpCache instance
     :param instance_url: url to the instance file(on the internet)
-    This function will check, if the instance file is already in the cache and load it from there based on the
-    instance_url.
-    For EDGAR submissions: Before calling this method; extract the enclosure and copy the files to the cache.
-        i.e. Use CacheHelper.extract_edgar_enclosure()
-    :return:
+    :return: parsed XbrlInstance object containing all facts with additional information
     """
     instance_path: str = cache.cache_file(instance_url)
     return parse_ixbrl(instance_path, cache, instance_url)
@@ -369,15 +368,12 @@ def parse_ixbrl_url(instance_url: str, cache: HttpCache) -> XbrlInstance:
 def parse_ixbrl(instance_path: str, cache: HttpCache, instance_url: str or None = None, encoding=None) -> XbrlInstance:
     """
     Parses a inline XBRL (iXBRL) instance file.
+
     :param instance_path: path to the submission you want to parse
     :param cache: HttpCache instance
     :param instance_url: url to the instance file(on the internet)
     :param encoding: optionally specify a file encoding
-    This function will check, if the instance file is already in the cache and load it from there based on the
-    instance_url.
-    For EDGAR submissions: Before calling this method; extract the enclosure and copy the files to the cache.
-        i.e. Use CacheHelper.extract_edgar_enclosure()
-    :return:
+    :return: parsed XbrlInstance object containing all facts with additional information
     """
     """
     In contrary to the XBRL-parse method we use here the actual root instead of the root element!!!

xbrl/linkbase.py

@@ -413,8 +413,8 @@ def parse_linkbase_url(linkbase_url: str, linkbase_type: LinkbaseType, cache: Ht
 
     :param linkbase_url: full link to the linkbase
     :param linkbase_type: type of the linkbase (calculation-, label-, presentation-, ...)
-    :param cache: http cache instance
-    :return: parsed Linkbase object
+    :param cache: :class:`xbrl.cache.HttpCache` instance
+    :return: parsed :class:`xbrl.linkbase.Linkbase` object
     """
     if not linkbase_url.startswith('http'): raise XbrlParseException(
         'This function only parses remotely saved linkbases. Please use parse_linkbase to parse local linkbases')
@@ -435,7 +435,7 @@ def parse_linkbase(linkbase_path: str, linkbase_type: LinkbaseType, linkbase_url
     :param linkbase_url: if the locator of the linkbase contain relative references to concepts
         (i.e.: './../schema.xsd#Assets') the url has to be set so that the parser can connect
         the locator with concept from the taxonomy
-    :return: parsed Linkbase object
+    :return: parsed :class:`xbrl.linkbase.Linkbase` object
     """
     if linkbase_path.startswith('http'): raise XbrlParseException(
         'This function only parses locally saved linkbases. Please use parse_linkbase_url to parse remote linkbases')

xbrl/taxonomy.py

@@ -1,10 +1,5 @@
 """
 This module contains all classes and functions necessary for parsing Taxonomy schema files.
-
-A Taxonomy schema defines the reportable concepts and links the linkbases to
-describe the relationships between the concepts.
-Taxonomy schemas can import multiple different taxonomy schemas.
-
 """
 import logging
 import os
@@ -436,15 +431,7 @@ class TaxonomySchema:
     def __init__(self, schema_url: str, namespace: str):
         """
         The imports array stores an array of all Schemas that are imported.
-        The current Taxonomy Schema can override the extended schemas in the following way:
-        1. Addition of new concepts:
-            New concepts are added in this TaxonomySchema to extend the concepts declared in the base Taxonomy schemas
-        2. Addition of resources:
-            The Label Linkbase of this taxonomy can add new labels to existing concepts from the base taxonomy
-        3. Overriding of relationships:
-            All Linkbases of this taxonomy can override i.e the order of concepts in a definition linkbase
-        4. Overriding of resources:
-            The Label Linkbase of this taxonomy can override the labels of the base taxonomy!
+
 
         :param schema_url:
         :param namespace:
@@ -506,9 +493,10 @@ def parse_common_taxonomy(cache: HttpCache, namespace: str) -> TaxonomySchema or
 def parse_taxonomy_url(schema_url: str, cache: HttpCache) -> TaxonomySchema:
     """
     Parses a taxonomy schema file from the internet
-    :param schema_url:
-    :param cache:
-    :return:
+
+    :param schema_url: full link to the taxonomy schema
+    :param cache: :class:`xbrl.cache.HttpCache` instance
+    :return: parsed :class:`xbrl.taxonomy.TaxonomySchema` object
     """
     if not schema_url.startswith('http'): raise XbrlParseException(
         'This function only parses remotely saved taxonomies. Please use parse_taxonomy to parse local taxonomy schemas')
@@ -520,11 +508,12 @@ def parse_taxonomy_url(schema_url: str, cache: HttpCache) -> TaxonomySchema:
 def parse_taxonomy(schema_path: str, cache: HttpCache, schema_url: str or None = None) -> TaxonomySchema:
     """
     Parses a taxonomy schema file.
+
     :param schema_path: url to the schema (on the internet)
-    :param cache: HttpCache instance
+    :param cache: :class:`xbrl.cache.HttpCache` instance
     :param schema_url: if this url is set, the script will try to fetch additionally imported files such as linkbases or
-    imported schemas from the remote location. If this url is None, the script will try to find those resources locally.
-    :return:
+        imported schemas from the remote location. If this url is None, the script will try to find those resources locally.
+    :return: parsed :class:`xbrl.taxonomy.TaxonomySchema` object
     """
     if schema_path.startswith('http'): raise XbrlParseException(
         'This function only parses locally saved taxonomies. Please use parse_taxonomy_url to parse remote taxonomy schemas')