Copy from hub docs modified to fit the persistence repo

2023-11-28 13:36:40 -05:00 · 2023-11-28 13:36:40 -05:00 · c2bbece21c
commit c2bbece21c
12 changed files with 1290 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1,3 @@
+build
+docs
+.idea
--- a/40
+++ b/40
@ -0,0 +1,40 @@
+# Minimal makefile for Sphinx documentation
+#
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+UNAME_S := $(shell uname -s)
+SED_FLAG = -i
+ifeq ($(UNAME_S),Darwin)
+	SED_FLAG = -e
+endif
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+all: %
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@echo 'Create the trees for the files'
+	@tree -I '__pycache__' ../cerc_persistence/cerc_persistence/models/ | convert -size 404x310 label:@- ./source/models.png
+	@tree -I '__pycache__' ../cerc_persistence/cerc_persistence/repositories/ | convert -size 496x394 -quality 100 label:@- ./source/repositories.png
+	@tree -I '__pycache__' ../cerc_persistence/cerc_persistence/ | convert -size 496x394 -quality 100 label:@- ./source/cerc_persistence.png
+
+	@echo 'Create the uml'
+	@python3 ./create_dot.py
+	@dot -n ./source/uml.dot -Tpng -Nshape=rect -o ./source/dot.png
+
+
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+	@rm ./source/*.png
+	@rm ./source/uml.dot
+
--- a/README.md
+++ b/README.md
@ -0,0 +1,171 @@
+# libs_doc
+
+Automatic tool to create the libs' documentation
+
+# Windows compilation instructions using Windows Subsystem for Linux (WSL2)
+
+Open Powershell as an Administrator and run
+```
+wsl.exe --install
+```
+
+This will enable the Windows Subsystem for Linux and install the command line version of Ubuntu. Once finished, restart your computer. When you login again, Ubuntu will open automatically. Enter in a new username and password for the Ubuntu installation.
+
+Update and upgrade the apt packages
+```
+sudo apt update && sudo apt upgrade -y
+```
+
+Next, follow the steps outlined in the [Linux compilation section](#linux-compilation) below.
+
+Create a new directory called *cerc_docs* and navigate to the new directory
+```
+mkdir cerc_docs && cd cerc_docs
+```
+
+Clone the *cerc_persistence_doc* repository
+```
+git clone https://nextgenerations-cities.encs.concordia.ca/gitea/CERC/cerc_persistence_doc
+```
+
+Clone the *cerc_persistence* repository
+```
+git clone https://nextgenerations-cities.encs.concordia.ca/gitea/CERC/cerc_persistence
+```
+
+Navigate to the *cerc_persistence_doc* directory
+```
+cd cerc_persistence_doc
+```
+
+Compile the PDF
+```
+make latexpdf
+```
+
+The compiled *cercpersistencereferencemanual.pdf* will be created in
+```
+cerc_docs/cerc_persistence_doc/build/latex/
+```
+
+# Mac compilation
+Open terminal and install homebrew
+```
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+Install Sphinx
+```
+brew install sphinx-doc
+echo 'export PATH="/usr/local/opt/sphinx-doc/bin:$PATH"' >> ~/.zshrc
+```
+
+Install latexmk
+```
+sudo tlmgr install latexmk
+```
+
+Install BasicTeX
+```
+brew install --cask basictex
+```
+
+Install texlive
+```
+brew install texlive
+```
+
+Install Tree
+```
+brew install tree
+```
+
+Install ImageMagick
+```
+brew install imagemagick
+```
+
+Install Graphviz
+```
+brew install graphviz
+```
+
+Create a new directory called *cerc_docs* and navigate to the new directory
+```
+mkdir cerc_docs && cd cerc_docs
+```
+
+Clone the *cerc_persistence_doc* repository
+```
+git clone https://nextgenerations-cities.encs.concordia.ca/gitea/CERC/cerc_persistence_doc
+```
+
+Clone the *cerc_persistence* repository
+```
+git clone https://nextgenerations-cities.encs.concordia.ca/gitea/CERC/cerc_persistence
+```
+
+Navigate to the *cerc_persistence_doc* directory
+```
+cd cerc_persistence_doc
+```
+
+Compile the PDF
+```
+make latexpdf
+```
+
+The compiled *cercpersistencereferencemanual.pdf* will be created in
+```
+cerc_docs/cerc_persistence_doc/build/latex/
+```
+
+
+# Linux compilation
+
+Some dependencies are needed in Linux systems, this manual cover only debian based distros (like Ubuntu), but the process should be similar for other Linux distributions
+
+- Build essential
+
+```
+sudo apt install build-essential
+```
+
+- Sphinx
+
+```
+sudo apt install sphinx
+```
+
+- Latex
+
+```
+sudo apt install texlive-latex-extra latexmk
+```
+
+- Tree
+```
+sudo apt install tree
+```
+
+- ImageMagick
+```
+sudo apt install libpng-dev libjpeg-dev libtiff-dev imagemagick
+```
+
+- Graphviz
+```
+sudo apt install graphviz
+```
+
+Some changes are mandatory in the policymap of imagemagick (/etc/ImageMagick-6/policy.xml)
+
+Disable security policy by commenting or deleting the following line
+```
+<policy domain="path"rights="none" pattern="@*"/>
+```
+To prevent size errors change the width and height values to 16MP
+```
+<policy domain="resource" name="width" value="16MP"/>
+<policy domain="resource" name="height" value="16MP"/>
+```
--- a/create_dot.py
+++ b/create_dot.py
@ -0,0 +1,43 @@
+from pathlib import Path
+result = list(Path("../hub/hub/city_model_structure").rglob("*.[pP][yY]"))
+dot_file = './source/uml.dot'
+dot = 'digraph { \n ratio="fill"; \nsize="16.6,23.4!";\nmargin=0; \n  \n'
+class_line = None
+for file_path in result:
+  with open(file_path) as file:
+    lines = file.readlines()
+    for line in lines:
+      if 'class ' == line[0:6]:
+        line = line.replace('class ', '"')\
+          .replace(':', '"')\
+          .replace('(', '" -> "')\
+          .replace(')', '"[arrowhead="empty"] ')\
+          .replace(' "', '')\
+          .replace('->', '-> "')
+        class_line = line
+        if ' -> ' in line:
+          class_line = line.split(' -> ')[0]
+        if '"City"' == line[0:6]:
+          line = line[0:6] + ' [pos="0,1!"]\n'
+        dot += line
+      if 'def ' in line[2:8]:
+        if ' -> ' in line:
+          reference = line.split(' -> ')[1].replace(':', '').strip(' ()[]{},').replace('\n', '')
+          reference = reference.replace('Union', '').replace('List', '').replace('float', '').replace('str', '')
+          reference = reference.replace('bool', '').replace('None', '').replace(',', '')
+          reference = reference.replace(' ', '').replace('np.ndarray', '').replace('dict', '')
+          reference = reference.replace('[', '').replace(']', '').replace('Path', '').replace('pd.DataFrame', '')
+          reference = reference.replace('Trimesh', '').replace('}', '').replace('Edge)', '')
+          reference = reference.replace('(', '').replace(')', '')
+
+          if 'Point' not in reference:
+            reference = reference.replace('int', '')
+
+          if reference != '':
+            dot += f'"{reference}"-> {class_line}[arrowhead="diamond"] '
+
+
+dot += '}'
+
+with open(dot_file, 'w') as file:
+  file.write(dot.replace(' \n', ' ').replace('\n', ' ').replace('ABC, ', '').replace(' " ', ' '))
--- a/make.bat
+++ b/make.bat
@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
--- a/source/_ext/cerc_documenter.py
+++ b/source/_ext/cerc_documenter.py
@ -0,0 +1,159 @@
+from typing import Optional, Any
+
+from docutils.statemachine import StringList
+from sphinx.application import Sphinx
+from sphinx.ext.autodoc import ClassDocumenter, PropertyDocumenter, MethodDocumenter, bool_option
+from sphinx.util import inspect
+from sphinx.util.typing import restify
+
+
+def setup(app: Sphinx) -> None:
+  app.setup_extension('sphinx.ext.autodoc')  # Require autodoc extension
+  app.add_autodocumenter(CercClassDocumenter)
+  app.add_autodocumenter(CercPropertyDocumenter)
+  app.add_autodocumenter(CercMethodDocumenter)
+
+
+class CercMethodDocumenter(MethodDocumenter):
+  objtype = 'cercmethod'
+  directivetype = 'method'
+  member_order = 50
+  priority = MethodDocumenter.priority + 10
+
+  @staticmethod
+  def _get_type(sig_return):
+    types = sig_return.replace('Optional', '').replace('List', '').split('.')
+    prefix = ''
+    if types[0][0] in '[(':
+      prefix = types[0][0]
+    return f'{prefix}{types[len(types) -1]}'
+
+  def format_signature(self, **kwargs: Any) -> str:
+    sig = super().format_signature(**kwargs)
+    if '->' in sig:
+      sig_pars = sig.split(' -> ')
+      return_type = CercMethodDocumenter._get_type(sig_pars[1])
+      return_str = f'{return_type}'
+      if 'Optional' in sig_pars[1]:
+        return_str = f'Optional{return_str}'
+      return f'{sig_pars[0]} -> {return_str}'
+    return sig
+
+  def add_content(self, more_content: Optional[StringList], no_docstring: bool = False) -> None:
+    source_name = self.get_sourcename()
+    docstrings = self.get_doc()
+    self.content_indent = '   '
+    for i, line in enumerate(self.process_doc(docstrings)):
+      if ':return:' in line:
+        line = line.replace(':return:', '**Returns**')
+      elif ':param ' in line:
+        line = line.replace(':param ', '**Parameter** ')
+        line = line.replace(':', ' ')
+      elif ':alert:' in line:
+        line = line.replace(':alert:', '|alert|')
+      elif ':cat:' in line:
+        line = line.replace(':cat:', '|cat|')
+      self.add_line(f'{line}\n', source_name, i)
+
+
+class CercPropertyDocumenter(PropertyDocumenter):
+  objtype = 'cercproperty'
+  directivetype = 'property'
+  member_order = 60
+  priority = PropertyDocumenter.priority + 10
+
+  @staticmethod
+  def _get_type(annotations):
+    if len(annotations) == 0:
+      return annotations
+    return_str = str(annotations['return']).replace('typing.', '')
+    if 'Union' in return_str:
+      return_str = return_str.replace('Union', 'Optional').replace(', None', '').replace('None, ', '')
+      return_str = return_str.replace('NoneType, ','').replace(', NoneType', '')
+    if 'List' in return_str:
+      return_str = return_str.replace('typing.List', '').replace('List', '')
+    if "<class '" in return_str:
+      return_str = return_str.replace("<class '", '').replace("'>", '')
+    if '.' in return_str:
+      for i, c in enumerate(reversed(return_str)):
+        if c not in '])':
+          types_str = return_str.split('.')
+          if 'Optional' in return_str:
+            return_str = f'{types_str[0][0:8+i]}{types_str[len(types_str)-1]}'
+          else:
+            return_str = f'{types_str[0][0:i]}{types_str[len(types_str)-1]}'
+          break
+    return_str = return_str.replace('~', '').replace('Type', '')
+    return return_str
+
+  def add_directive_header(self, sig: str) -> None:
+    name = self.format_name()
+    source_name = self.get_sourcename()
+    annotations = self.get_attr(self.object.fget, '__annotations__', None)
+    self.retann = CercPropertyDocumenter._get_type(annotations)
+    for i, sig_line in enumerate(sig.split("\n")):
+      self.add_line(f'.. py:property:: {name}({sig_line}) {(f" -> {self.retann}" if self.retann else "")}', source_name)
+    if self.objpath:
+      self.add_line(f'   :module: {self.modname}', source_name)
+    if inspect.isabstractmethod(self.object):
+      self.add_line('      :abstractmethod:', source_name)
+    self.add_line(f'      :property:', source_name)
+
+  def add_content(self, more_content: Optional[StringList], no_docstring: bool = False) -> None:
+    source_name = self.get_sourcename()
+    docstrings = self.get_doc()
+    self.content_indent = '   '
+    if not no_docstring:
+      if not docstrings:
+        docstrings.append([])
+      for i, line in enumerate(self.process_doc(docstrings)):
+        if ':return:' in line:
+          line = line.replace(':return:', '**Returns**')
+        elif ':alert:' in line:
+          line = line.replace(':alert:', '|alert|')
+        self.add_line(f'{line}\n', source_name, i)
+
+
+class CercClassDocumenter(ClassDocumenter):
+  objtype = 'cercclass'
+  directivetype = 'class'
+  priority = 10 + ClassDocumenter.priority
+  option_spec = dict(ClassDocumenter.option_spec)
+  option_spec['hex'] = bool_option
+
+  def get_bases(self, source_name):
+    bases = []
+    if hasattr(self.object, '__orig_bases__') and len(self.object.__orig_bases__):
+      bases = [restify(cls) for cls in self.object.__orig_bases__]
+    elif hasattr(self.object, '__bases__') and len(self.object.__bases__):
+      # A normal class
+      bases = [restify(cls) for cls in self.object.__bases__]
+    if ':class:`object`' in bases:
+      bases.remove(':class:`object`')
+    cleaned_bases = []
+    for base in bases:
+      base_tmp = base.replace('`', '').split('.')
+      base_tmp = base_tmp[len(base_tmp)-1]
+      cleaned_bases.append(base_tmp)
+    if len(cleaned_bases) != 0:
+      self.add_line('   Inherit: %s' % ', '.join(cleaned_bases), source_name)
+      self.add_line(' ', source_name)
+
+  def add_directive_header(self, sig: str) -> None:
+    prefix = f'.. py:class:: '
+    name = self.format_name()
+    source_name = self.get_sourcename()
+    self.add_line('%s%s%s' % (prefix, name, sig), source_name)
+    if self.analyzer and '.'.join(self.objpath) in self.analyzer.finals:
+      self.add_line('   :final:', source_name)
+    self.get_bases(source_name)
+
+  def add_content(self, more_content: Optional[StringList], no_docstring: bool = False) -> None:
+    source_name = self.get_sourcename()
+    docstrings = self.get_doc()
+    self.content_indent = '   '
+    if not no_docstring:
+      if not docstrings:
+        docstrings.append([])
+      for i, line in enumerate(self.process_doc(docstrings)):
+        self.add_line(line, source_name)
--- a/source/_static/alert.png
+++ b/source/_static/alert.png
--- a/source/_static/cat.png
+++ b/source/_static/cat.png
--- a/source/_static/custom.css
+++ b/source/_static/custom.css
@ -0,0 +1,7 @@
+@import url("default.css");
+
+.center
+
+.tiny {
+    font-size: 2px;
+}
--- a/source/_templates/layout.html
+++ b/source/_templates/layout.html
@ -0,0 +1,5 @@
+{% extends "!layout.html" %}
+
+{% block extrahead %}
+<link rel="stylesheet" type="text/css" href="{{ pathto('_static/custom.css', 1) }}" />
+{% endblock %}
--- a/source/conf.py
+++ b/source/conf.py
@ -0,0 +1,77 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# 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 os
+import sys
+
+sys.path.insert(0, os.path.abspath('../../hub/'))
+sys.path.append(os.path.abspath("./_ext"))
+sys.path.append(os.path.abspath("./_static"))
+sys.path.append(os.path.abspath("."))
+
+from hub.version import __version__
+
+sys.setrecursionlimit(1500)
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'CERC hub reference manual'
+copyright = '2021, Guille Gutierrez and Pilar Monsalvete'
+author = 'CERC Next-Generation Cities'
+
+# The full version, including alpha/beta/rc tags
+release = __version__
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.    'sphinx.ext.autodoc',
+extensions = [
+   'sphinx.ext.autodoc',
+   'cerc_documenter'
+]
+autodoc_mock_imports = ["pyproj", "numpy", "trimesh", "Node", "Edge", "pandas", "typing", "xmltodict", "geomeppy",
+                        "parseidf", "rhino3dm", "pyecore", "EPackage", "pyecore.ecore", "geopandas", "shapely",
+                        "hub.catalog_factories.greenery.greenery_catalog", "catalog_factories.greenery.greenery_catalog"
+                        ]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+source_suffix = ['.rst', '.md']
+
+# 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 = []
+
+
+# -- 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'
+
+# 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']
+
+todo_include_todos = True
+
+master_doc = 'index'
+
+latex_elements = {'extraclassoptions': 'openany,oneside'}
--- a/source/index.rst
+++ b/source/index.rst
@ -0,0 +1,750 @@
+.. _how to use the hub: https://todo/
+
+.. _development manual: https://todo/
+
+.. _catalogs manual: https://todo
+
+.. |alert| image:: ./_static/alert.png
+  :width: 15
+  :alt: Alert
+
+.. |cat| image:: ./_static/cat.png
+  :width: 30
+  :alt: Cat
+
+CERC HUB' reference manual
+=====================================
+.. toctree::
+   :maxdepth: 4
+   :caption: Contents:
+
+CERC HUB' reference manual
+=====================================
+Authors
+*************************
+
+* Guillermo Gutierrez Morote
+* Pilar Monsalvete Alvarez de Uribarri
+
+Contributors
+*************************
+
+* Seyedehrabeeh Hosseinihaghighi
+* Milad Aghamohamadnia
+* Peter Yefi
+* Koa Wells
+* Sanam Dabirian
+* Soroush Samareh Abolhassani
+
+About the HUB
+*************************
+
+This document contains the essential documentation for the CERC HUB, a set of classes, factories, and helpers that simplifies the research at urban scale in multiples domains; these components are designed around three central axes, **extensibility**, **code clarity** and **consistency** as we intend to allow domain experts to perform urban scale simulations with multiple programs and enrich the city from several data sources.
+HUB is composed of four main components: **city model structure**, **factories**, **catalogs** and, **helpers**.
+
+- **City model structure** is the set of classes designed to be familiar to the domain experts; this familiarity will be possible thanks to using a *standard-based* approach in order to flatten the learning curve. These classes compose the CERC *data model* that provides a simple way to study cities at an urban scale after the enriching process.
+- **Factories** are pieces of code in charge of import and export information in and out of the **data model** they will perform the needed conversions to read or write different formats such as epw weather files, insel files or citygml. these factories are mean to be extended, allowing the HUB ecosystem to expand with new formats.
+- **Catalogs** are datasets used in the enrichment of the city that can also be used by third party consumers like researchers or simulations software.
+- **Helpers** are sets of general tools used by any of the other parts and does not fit in any of the previous categories.
+
+City model structure
+=====================================
+
+The **city model structure** contains the common data model intended to represent a city digital twin, CERC team and contributors, will further extend these classes to include other domains, in the following sections, researchers and developers could find information about the methods and properties exposed by the city model structure classes.
+
+.. important::
+
+   Please take a look to HUB tutorial to see how to use HUB for your own research
+
+   [`how to use the hub`_]
+
+City model structure UML
+************************
+
+.. image:: dot.png
+   :width: 575
+
+.. raw:: latex
+
+    \clearpage
+
+Folder structure
+******************
+
+city_model_structure
+^^^^^^^^^^^^^^^^^^^^^^
+Main city objects.
+
+.. image:: ./city_model_structure.png
+   :width: 200
+
+attributes
+^^^^^^^^^^^^^^^^^^^^^^
+Geometrical and non physical components of the city.
+
+.. image:: ./attributes.png
+   :width: 200
+
+building_demand
+^^^^^^^^^^^^^^^^^^^^^^
+Main classes to model building energy demand.
+
+.. image:: ./building_demand.png
+   :width: 300
+
+energy_systems
+^^^^^^^^^^^^^^^^^^^^^^
+Main classes to model energy systems.
+
+.. image:: ./energy_systems.png
+   :width: 300
+
+iot
+^^^^^^^^^^^^^^^^^^^^^^
+Classes to model IoT devices.
+
+.. image:: ./iot.png
+   :width: 250
+
+.. raw:: latex
+
+    \clearpage
+
+full schema
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ./city_model_structure_complete.png
+   :width: 300
+
+Classes
+****************************
+
+City
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.city.City
+   :members:
+
+CityObject
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.city_object.CityObject
+   :members:
+
+City Objects Cluster
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.city_objects_cluster.CityObjectsCluster
+   :members:
+
+Building
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.building.Building
+   :members:
+
+Parts Consisting Building
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.parts_consisting_building.PartsConsistingBuilding
+   :members:
+
+Buildings Cluster
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.buildings_cluster.BuildingsCluster
+   :members:
+
+Network
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.network.Network
+   :members:
+
+Level of detail
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.level_of_detail.LevelOfDetail
+   :members:
+
+Edge
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.attributes.edge.Edge
+   :members:
+
+Node
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.attributes.node.Node
+   :members:
+
+Plane
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.attributes.plane.Plane
+   :members:
+
+Point
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.attributes.point.Point
+   :members:
+
+Polygon
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.attributes.polygon.Polygon
+   :members:
+
+Polyhedron
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.attributes.polyhedron.Polyhedron
+   :members:
+
+Record
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.attributes.record.Record
+   :members:
+
+Schedule
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.attributes.schedule.Schedule
+   :members:
+
+Time Series
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.attributes.time_series.TimeSeries
+   :members:
+
+Appliances
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.building_demand.appliances.Appliances
+   :members:
+
+Household
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.building_demand.household.Household
+   :members:
+
+Internal Gain
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.building_demand.internal_gain.InternalGain
+   :members:
+
+Internal Zone
+^^^^^^^^^^^^^^^^^^^^^^
+.. note:: The internal zone class represents each of the internal zones described in the geometry when imported.
+
+   This imported geometry can be later on divided in different thermal zones in a workflow (e.g. if the building with no interiors defined (LoD up to 3), it will produce one interior zone. Later on, this can be divided by storey and create one thermal zone per each).
+
+   Also, several usages can be associated with that internal zone. This usages are described in the Usage class, which has not only the parameters that describe each usage, but also the percentage of the internal zone volume that is affected by that specific use.
+
+.. autocercclass:: hub.city_model_structure.building_demand.internal_zone.InternalZone
+   :members:
+
+Layer
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.building_demand.layer.Layer
+   :members:
+
+Lighting
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.building_demand.lighting.Lighting
+   :members:
+
+Occupancy
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.building_demand.occupancy.Occupancy
+   :members:
+
+Storey
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.building_demand.storey.Storey
+   :members:
+
+Surface
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.building_demand.surface.Surface
+   :members:
+
+Thermal Boundary
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.building_demand.thermal_boundary.ThermalBoundary
+   :members:
+
+Thermal Control
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.building_demand.thermal_control.ThermalControl
+   :members:
+
+Thermal Opening
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.building_demand.thermal_opening.ThermalOpening
+   :members:
+
+Thermal Zone
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.building_demand.thermal_zone.ThermalZone
+   :members:
+
+Usage
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.building_demand.usage.Usage
+   :members:
+
+Plant
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.greenery.plant.Plant
+   :members:
+
+Soil
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.greenery.soil.Soil
+   :members:
+
+Vegetation
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.greenery.vegetation.Vegetation
+   :members:
+
+Sensor
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.iot.sensor.Sensor
+   :members:
+
+Sensor Measure
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.iot.sensor_measure.SensorMeasure
+   :members:
+
+Sensor Type
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.iot.sensor_type.SensorType
+   :members:
+
+Station
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.city_model_structure.iot.station.Station
+   :members:
+
+Factories
+=====================================
+
+Factories are divided into Imports and Exports, depending on if they are used to enrich (Import) the *city model structure* or to deliver third party defined formats (Export) such as **INSEL** or **IDF** file, the factories could be extended to include new imports and outputs providing an additional level of abstraction to researchers.
+
+|alert| Please, note that the private methods, the ones starting with an underscore character (_), documented in the factories are mean to be called by using the **handler** parameter; this parameter must contain the method name without the _ character.
+
+.. note::
+   For instance, to use _citygml handler in the Geometry factory, the handler parameter value needs to be 'citygml'
+
+|alert| **This documentation includes only the base factories classes as these are the intended entry points for the Import/Export functionality.**
+
+.. important::
+
+   Please refer to the development manual if you want to create your own factories.
+
+   [`development manual`_]
+
+.. raw:: latex
+
+    \clearpage
+
+Folder structure
+******************
+
+Imports
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ./imports.png
+   :width: 250
+
+Exports
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ./exports.png
+   :width: 250
+
+.. raw:: latex
+
+    \clearpage
+
+
+Imports Classes
+***************
+
+Construction Factory
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.imports.construction_factory.ConstructionFactory
+   :members:
+   :private-members:
+
+Geometry Factory
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.imports.geometry_factory.GeometryFactory
+   :members:
+   :private-members:
+
+Usage Factory
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.imports.usage_factory.UsageFactory
+   :members:
+   :private-members:
+
+Weather Factory
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.imports.weather_factory.WeatherFactory
+   :members:
+   :private-members:
+
+.. raw:: latex
+
+    \clearpage
+
+Exports
+*******
+
+Export Factory
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.exports.exports_factory.ExportsFactory
+   :members:
+   :private-members:
+
+Catalogs
+=====================================
+
+In its simplest form, a catalogue is a file or group of files that provide technical and/or commercial information regarding components that form a system within any domain. The components are listed with relevant details and associated data is tabulated. Also listed are the dominant/standard configurations in which the components may be used to satisfy use-cases/output requirements (as supplied by component manufacturer/standard organisations).
+
+
+.. note::
+   Examples, Heat Pump catalogue should consist of the heat pump models produced, heat pump type, manufacturer name, output temperatures, nominal capacities, typical configurations for the heat pumps (e.g., configurations when used for space heating only, Domestic Hot Water/DHW purposes only, both space heating and DHW, combinations with solar thermal/PV), storage tank data, circulation pump data, compressor type and associated technical data, valve types etc.
+
+.. important::
+
+   Please refer to the catalogs manual if you want to create or extend your own catalogs.
+
+   [`catalogs manual`_]
+
+Folder structure
+******************
+
+Catalogs
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ./catalogs.png
+   :width: 240
+
+Catalog Base Class
+*******************
+
+Catalog
+^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.catalog.Catalog
+   :members:
+
+.. raw:: latex
+
+    \clearpage
+
+Greenery
+***************
+
+Greenery Catalog Factory
+^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.greenery_catalog_factory.GreeneryCatalogFactory
+   :members:
+   :private-members:
+
+Greenery Content Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.greenery.content.Content
+   :members:
+
+Greenery Plant Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.greenery.plant.Plant
+   :members:
+
+Greenery Plant Percentage Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.greenery.plant_percentage.PlantPercentage
+   :members:
+
+Greenery Plant Soil Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.greenery.soil.Soil
+   :members:
+
+Greenery Vegetation Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.greenery.vegetation.Vegetation
+   :members:
+
+.. raw:: latex
+
+    \clearpage
+
+Construction
+***************
+
+Construction Catalog Factory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.construction_catalog_factory.ConstructionCatalogFactory
+   :members:
+   :private-members:
+
+Construction Content Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.construction.content.Content
+   :members:
+
+Construction Archetype Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.construction.archetype.Archetype
+   :members:
+
+Construction Construction Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.construction.construction.Construction
+   :members:
+
+Construction Layer Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.construction.layer.Layer
+   :members:
+
+Construction Material Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.construction.material.Material
+   :members:
+
+Construction Window Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.construction.window.Window
+   :members:
+
+.. raw:: latex
+
+    \clearpage
+
+Costs
+***************
+
+Costs Catalog Factory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.costs_catalog_factory.CostsCatalogFactory
+   :members:
+   :private-members:
+
+Costs Content Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.cost.content.Content
+   :members:
+
+Costs Archetype Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.cost.archetype.Archetype
+   :members:
+
+Costs Capital Cost Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.cost.capital_cost.CapitalCost
+   :members:
+
+Costs Chapter Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.cost.chapter.Chapter
+   :members:
+
+Costs Fuel Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.cost.fuel.Fuel
+   :members:
+
+Costs Income Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.cost.income.Income
+   :members:
+
+Costs Item Description Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.cost.item_description.ItemDescription
+   :members:
+
+Costs Operational Cost Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.cost.operational_cost.OperationalCost
+   :members:
+
+.. raw:: latex
+
+    \clearpage
+
+Energy Systems
+***************
+
+Energy Systems Catalog Factory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.energy_systems_catalog_factory.EnergySystemsCatalogFactory
+   :members:
+   :private-members:
+
+Energy Systems Content Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.energy_systems.content.Content
+   :members:
+
+Energy Systems Archetype Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.energy_systems.archetype.Archetype
+   :members:
+
+Energy Systems Distribution System Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.energy_systems.distribution_system.DistributionSystem
+   :members:
+
+Energy Systems Emission System Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.energy_systems.emission_system.EmissionSystem
+   :members:
+
+Energy Systems Generation System Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.energy_systems.generation_system.GenerationSystem
+   :members:
+
+Energy Systems Energy Systems Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.energy_systems.system.System
+   :members:
+
+.. raw:: latex
+
+    \clearpage
+
+Usage
+************
+
+Usage Catalog Factory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.usage_catalog_factory.UsageCatalogFactory
+   :members:
+   :private-members:
+
+Usage Content Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.usages.content.Content
+   :members:
+
+Usage Appliances Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.usages.appliances.Appliances
+   :members:
+
+Usage Content Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.usages.content.Content
+   :members:
+
+Usage Domestic Hot Water Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.usages.domestic_hot_water.DomesticHotWater
+   :members:
+
+Usage Internal Gain Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.usages.internal_gain.InternalGain
+   :members:
+
+Usage Lighting Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.usages.lighting.Lighting
+   :members:
+
+Usage Occupancy Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.usages.occupancy.Occupancy
+   :members:
+
+Usage Schedule Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.usages.schedule.Schedule
+   :members:
+
+Usage Thermal Control Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.usages.thermal_control.ThermalControl
+   :members:
+
+Usage Usage Data Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autocercclass:: hub.catalog_factories.data_models.usages.usage.Usage
+   :members:
+
+.. raw:: latex
+
+    \clearpage
+
+
+Helpers
+=======
+
+CERC hub provides a set of *helpers* that will simplify certain operations; these helpers are mean to be freely used at any point and therefore could be consumed from several places.
+
+Folder structure
+******************
+
+.. image:: ./helpers.png
+   :width: 300
+
+.. raw:: latex
+
+    \clearpage
+
+Configuration Helper
+********************
+.. autocercclass:: hub.helpers.configuration_helper.ConfigurationHelper
+   :members:
+
+.. raw:: latex
+
+    \clearpage
+
+Constants
+********************
+.. include:: constants.rst
+
+Geometry Helper
+********************
+.. autocercclass:: hub.helpers.geometry_helper.GeometryHelper
+   :members:
+
+Location
+********************
+.. autocercclass:: hub.helpers.location.Location
+   :members:
+
+Dictionaries
+********************
+.. autocercclass:: hub.helpers.dictionaries.Dictionaries
+   :members:
+
+Additional Files
+====================
+
+Readme
+***********
+
+`README.md <https://rs-loy-gitlab.concordia.ca/Guille/hub/-/blob/master/README.md>`_
+
+License
+************
+
+`LICENSE.md <https://rs-loy-gitlab.concordia.ca/Guille/hub/-/blob/master/LICENSE.md>`_
+
+Code of conduct
+************************
+
+`CODE_OF_CONDUCT.md <https://rs-loy-gitlab.concordia.ca/Guille/hub/-/blob/master/CODE_OF_CONDUCT.md>`_
+
+How to contribute
+************************
+
+`CONTRIBUTING.md <https://rs-loy-gitlab.concordia.ca/Guille/hub/-/blob/master/CONTRIBUTING.md>`_
+
+Coding style
+************************
+
+`PYGUIDE.md <https://rs-loy-gitlab.concordia.ca/Guille/hub/-/blob/master/PYGUIDE.md>`_
+
+.. raw:: latex
+
+   \tiny