add documentation

Signed-off-by: SofiaFaraci <[email protected]>
convince-project · May 21, 2024 · cb61b5d · cb61b5d
1 parent a796dca
commit cb61b5d
Show file tree

Hide file tree

Showing 11 changed files with 380 additions and 0 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,20 @@
+# Build documentation
+
+To build the documentation page, `plantuml` needs to be installed to generate the interactive overview picture.
+Please download version `v1.2024.4` and move it to the correct location:
+
+```bash
+wget https://github.com/plantuml/plantuml/releases/download/v1.2024.4/plantuml-bsd-1.2024.4.jar
+mkdir -p /usr/share/plantuml
+sudo mv plantuml-bsd-1.2024.4.jar /usr/share/plantuml/plantuml.jar 
+```
+
+Then the following command needs to be run to build the documentation:
+
+```bash
+cd <path-to-convince_toolchain>/docs
+pip install -r requirements.txt
+make html
+```
+
+It has been tested with Python 3.8.10 and pip version 24.0.
diff --git a/docs/make.bat b/docs/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
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,7 @@
+sphinx==7.1.2
+sphinx-rtd-theme==1.3.0rc1
+sphinxcontrib-mermaid==0.9.2
+sphinxcontrib-plantuml==0.29
+
+# sphinx-autodoc2==0.5.0
+myst-parser==3.0.1
diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css
@@ -0,0 +1,81 @@
+/* Custom CONVINCE theming for the RTD Sphinx theme */
+
+@import 'theme.css';
+
+/* Color variables */
+:root {
+    --convince-orange: #f59d27;
+    --convince-green: #0e9594;
+    --convince-pink: #e94667;
+    --convince-orange-light: #face93;
+    --convince-green-light: #86cac9;
+    --convince-pink-light: #f4a2b3;
+    --convince-orange-dark: #7a4e13;
+    --convince-green-dark: #074a4a;
+    --convince-pink-dark: #742333;
+}
+
+/* Side navigation top bit */
+.wy-side-nav-search {
+    background-color: darkgray;
+}
+
+/* Link on top of logo */
+.wy-side-nav-search a {
+    color: white;
+}
+.wy-side-nav-search a:hover {
+    color: white;
+}
+.wy-side-nav-search a:visited {
+    color: white;
+}
+
+/* Version in side bar */
+.wy-side-nav-search > div.version {
+   color: white;
+}
+
+/* Border of search field */
+.wy-side-nav-search input[type="text"] {
+    border-color: #000;
+}
+
+/* Side bar headers */
+.wy-side-nav-title {
+    background-color: var(--convince-orange);
+}
+
+/* Headers of boxes */
+.rst-content .note .admonition-title, .rst-content .note .wy-alert-title, .rst-content .seealso .admonition-title, .rst-content .seealso .wy-alert-title, .rst-content .wy-alert-info.admonition-todo .admonition-title, .rst-content .wy-alert-info.admonition-todo .wy-alert-title, .rst-content .wy-alert-info.admonition .admonition-title, .rst-content .wy-alert-info.admonition .wy-alert-title, .rst-content .wy-alert-info.attention .admonition-title, .rst-content .wy-alert-info.attention .wy-alert-title, .rst-content .wy-alert-info.caution .admonition-title, .rst-content .wy-alert-info.caution .wy-alert-title, .rst-content .wy-alert-info.danger .admonition-title, .rst-content .wy-alert-info.danger .wy-alert-title, .rst-content .wy-alert-info.error .admonition-title, .rst-content .wy-alert-info.error .wy-alert-title, .rst-content .wy-alert-info.hint .admonition-title, .rst-content .wy-alert-info.hint .wy-alert-title, .rst-content .wy-alert-info.important .admonition-title, .rst-content .wy-alert-info.important .wy-alert-title, .rst-content .wy-alert-info.tip .admonition-title, .rst-content .wy-alert-info.tip .wy-alert-title, .rst-content .wy-alert-info.warning .admonition-title, .rst-content .wy-alert-info.warning .wy-alert-title, .rst-content .wy-alert.wy-alert-info .admonition-title, .wy-alert.wy-alert-info .rst-content .admonition-title, .wy-alert.wy-alert-info .wy-alert-title {
+    background: var(--convince-green)
+}
+
+/* Content of boxes */
+.rst-content .note, .rst-content .seealso, .rst-content .wy-alert-info.admonition, .rst-content .wy-alert-info.admonition-todo, .rst-content .wy-alert-info.attention, .rst-content .wy-alert-info.caution, .rst-content .wy-alert-info.danger, .rst-content .wy-alert-info.error, .rst-content .wy-alert-info.hint, .rst-content .wy-alert-info.important, .rst-content .wy-alert-info.tip, .rst-content .wy-alert-info.warning, .wy-alert.wy-alert-info {
+    background: var(--convince-green-light);
+}
+
+/* Boxes in api documentation */
+html.writer-html4 .rst-content dl:not(.docutils) > dt, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt {
+    background: var(--convince-green-light);
+    color: var(--convince-green-dark);
+    border-top: 3px solid var(--convince-green);
+    padding: 6px;
+    position: relative;
+}
+
+/* All links */
+a {
+    color: var(--convince-pink);
+}
+
+/* Links on hover */
+a:hover {
+    color: var(--convince-pink-light);
+}
+
+/* Visited links */
+a:visited {
+    color: var(--convince-orange);
+}
diff --git a/docs/source/_templates/custom-class-template.rst b/docs/source/_templates/custom-class-template.rst
@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/docs/source/_templates/custom-module-template.rst b/docs/source/_templates/custom-module-template.rst
@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module Attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst  
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,76 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information
+
+project = 'MODEL2CODE'
+copyright = '2024'
+author = 'CONVINCE Consortium'
+
+release = '0.1'
+version = '0.1.0'
+
+# -- General configuration
+
+extensions = [
+    # 'sphinx.ext.autosummary',
+    # 'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    "sphinx.ext.napoleon",
+    "autoapi.extension",    
+    # 'myst_parser',
+    # 'sphinxcontrib.mermaid',
+    # 'sphinxcontrib.plantuml',
+    # 'autodoc2',
+]
+
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "show-module-summary",
+    "imported-members",
+]
+
+autoapi_dirs = ["../../src"]
+
+# intersphinx_mapping = {
+#     'python': ('https://docs.python.org/3/', None),
+#     'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+#     'networkx': ('https://networkx.org/documentation/stable/', None),
+# }
+intersphinx_disabled_domains = ['std']
+
+templates_path = ['_templates']
+
+# -- Options for HTML output
+
+html_theme = 'sphinx_rtd_theme'
+html_logo = 'convince_logo_horizontal_200p.png'
+html_theme_options = {
+    # 'analytics_id': 'G-XXXXXXXXXX',  #  Provided by Google in your dashboard
+    # 'analytics_anonymize_ip': False,
+    # 'logo_only': False,
+    # 'display_version': True,
+    # 'prev_next_buttons_location': 'bottom',
+    # 'style_external_links': False,
+    # 'vcs_pageview_mode': '',
+    # 'style_nav_header_background': '#FF5555',
+    # Toc options
+    # 'collapse_navigation': True,
+    # 'sticky_navigation': True,
+    # 'navigation_depth': 99,
+    # 'includehidden': True,
+    # 'titles_only': False
+}
+html_static_path = ['_static']
+# html_css_files = [
+#     'css/custom.css',
+# ]
+html_style = 'css/custom.css'
+
+# -- Options for EPUB output
+epub_show_urls = 'footnote'
+
+# autodoc2_packages = [
+#     "../../jani_generator/src/jani_generator",
+# ]
diff --git a/docs/source/convince_logo_horizontal_200p.png b/docs/source/convince_logo_horizontal_200p.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -0,0 +1,11 @@
+CONVINCE model2code Documentation
+===========================
+Welcome to the model2code tool documentation. 
+
+Contents
+----------
+.. toctree::
+   :maxdepth: 2
+
+   tutorials
+   api
diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst
@@ -0,0 +1,3 @@
+Tutorials
+=========
+To see the tutorial please see [model2code repository](https://convince-project.github.io/model2code/)
diff --git a/workflows/deploy.yml b/workflows/deploy.yml
@@ -0,0 +1,49 @@
+name: Deploy
+# Deploy sphinx documentation to GitHub Pages in docs branch
+
+on:
+    # Triggers the workflow on push or pull request events but only for the "main" branch
+    push:
+        branches: [ "main" ]
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        steps:
+            # Checkout the repository
+            - name: Checkout repository
+              uses: actions/checkout@v2
+            # install the dependencies
+            - name: Install dependencies
+              run: pip install -r docs/requirements.txt
+            # build the documentation
+            - name: Build documentation
+              run: |
+                    cd docs
+                    make html
+            # upload the documentation to GitHub Pages
+            - name: Upload artifact
+              uses: actions/upload-pages-artifact@v3
+              with:
+                    path: docs/build/html
+    deploy:
+        # Add a dependency to the build job
+        needs: build
+
+        # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+        permissions:
+            pages: write      # to deploy to Pages
+            id-token: write   # to verify the deployment originates from an appropriate source
+
+        # Deploy to the github-pages environment
+        environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+
+        runs-on: ubuntu-latest
+
+        steps:
+            # deploy the documentation to GitHub Pages
+            - name: Deploy to github pages
+              id: deployment
+              uses: actions/deploy-pages@v4