Commit 2f562d28 authored by Jan Dinkelbach's avatar Jan Dinkelbach
Browse files

add dockerfile and scripts for building documentation

parent 82420b15
......@@ -3,6 +3,7 @@
__pycache__
.idea
./cimpy/__pycache__
*.egg
# log files
*.log
FROM fedora:29
LABEL \
org.label-schema.schema-version = "1.0" \
org.label-schema.name = "cimpy" \
org.label-schema.license = "Apache" \
org.label-schema.vendor = "Institute for Automation of Complex Power Systems, RWTH Aachen University" \
org.label-schema.author.name = "Jan Dinkelbach" \
org.label-schema.author.email = "acs-software@eonerc.rwth-aachen.de" \
org.label-schema.vcs-url = "https://git.rwth-aachen.de/acs/public/cim/cimpy"
RUN dnf -y update
RUN dnf -y install \
make \
python3-sphinx \
python3-pip \
graphviz-devel
RUN dnf --refresh -y install \
python3-devel
RUN pip3 install sphinx_rtd_theme
# ADD . /cimpy
# WORKDIR /cimpy
\ No newline at end of file
sphinx-apidoc -F -f -H "cimpy" -o "./" "../"
python3 set_inheritance_diagram.py
make html
# 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('../'))
# -- Project information -----------------------------------------------------
project = 'cimpy'
copyright = '2019, Author'
author = 'Author'
# -- 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.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
'sphinx.ext.todo',
'sphinx_rtd_theme',
'sphinx.ext.inheritance_diagram',
'sphinx.ext.graphviz'
]
modindex_common_prefix = ['cimpy.']
inheritance_graph_attrs = dict(rankdir="TB", size='""')
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'en'
# 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 = ['_build', 'Thumbs.db', '.DS_Store']
# -- 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']
# -- Extension configuration -------------------------------------------------
# -- Options for todo extension ----------------------------------------------
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
\ No newline at end of file
.. cimgen documentation master file, created by
sphinx-quickstart on Thu Oct 24 10:37:56 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to cimgen's documentation!
==================================
Cimgen is a tool for generation and modification of CIM data.
Package Content
===============
An overview with all classes sorted by class name can be found in the :ref:`genindex` and one sorted by version can be found in the :ref:`modindex`. You can also use the search bar on the left.
.. toctree::
:maxdepth: 1
cimpy
Installation
============
.. code-block:: bash
$ git clone https://git.rwth-aachen.de/acs/core/cim/cimgen.git
$ cd cimgen
$ python setup.py develop
Usage
=====
CIM Import
""""""""""
Function for creating CIMpy objects out of a CIM topology.
.. code-block::
cimpy.cim_import(xml_files, cim_version, start_dict=None)
Arguments:
:xml_files: List of CIM RDF/XML files
:cim_version: String containing the CGMES version
Optional Arguments:
:start_dict: List of CIM classes which should be read, default: read all classes
Output:
:res: A map containing the CIMpy objects with the UUID as map key
`Example for CIM Import <https://git.rwth-aachen.de/acs/core/cim/cimgen/blob/cimexport/examples/quickstart/readCIGREMV.py>`_
CIM Export
""""""""""
Function for serialization of CIMpy objects to XML files.
.. code-block::
cimpy.cim_export(res, namespaces_dict, file_name, version):
Arguments:
:res: A dictionary containing all CIMpy objects accessible via the UUID
:namespaces_dict: A dictionary containing the namespaces of the original XML files
:file_name: String containing the name for the XML files.
:version: String containing the CGMES version
Output:
One XML file for each package in the CGMES version. The package name is added to the file name like [file_name]_[package].xml
`Example for CIM Generate <https://git.rwth-aachen.de/acs/core/cim/cimgen/blob/cimexport/examples/quickstart/exportCIGREMV.py>`_
from os import remove
import os
from tempfile import mkstemp
from shutil import move, copy
directory = os.getcwd()
if 'conf.py' in os.listdir(directory):
conf_file = os.path.abspath('conf.py')
real_conf_file = os.path.abspath('real_conf.py')
remove(conf_file)
copy(real_conf_file, conf_file)
if 'index.rst' in os.listdir(directory):
index_file = os.path.abspath('index.rst')
real_index_file = os.path.abspath('real_index.rst')
remove(index_file)
copy(real_index_file, index_file)
for file in os.listdir(directory):
if file.endswith(".rst"):
file_path = os.path.abspath(file)
fh, abs_path = mkstemp()
with open(fh, 'w') as new_file:
with open(file) as old_file:
for line in old_file:
if 'undoc-members' in line:
continue
else:
new_file.write(line)
if 'automodule' in line:
name = line.split('::')[1]
elif 'show-inheritance' in line:
new_file.write('Inheritance Diagram:\n')
new_file.write('""""""""""""""""""""\n')
new_file.write('.. inheritance-diagram:: ' + name)
new_file.write(' :parts: 1')
new_file.write('')
new_file.write('')
remove(file_path)
move(abs_path, file_path)
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment