feat(docs) add first iteration of compile script

.github/workflows/compile_docs.yml

@@ -0,0 +1,34 @@
+name: Build docs
+on: push
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - name: Setup Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: 3.7
+      - name: Install requirements
+        run: |
+          pip install --upgrade --upgrade-strategy eager sphinx recommonmark commonmark breathe sphinx-rtd-theme sphinx-markdown-tables sphinx-sitemap
+      - name: Build docs
+        run: docs/build.py
+      - name: Retrieve version
+        run: |
+          echo "::set-output name=VERSION_NAME::$(scripts/find_version.sh)"
+        id: version
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@3.7.1
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ACCESS_TOKEN: ${{ secrets.LVGL_BOT_TOKEN }}
+          REPOSITORY_NAME: lvgl/docs_compiled
+          BRANCH: gh-pages # The branch the action should deploy to.
+          FOLDER: out_html  # The folder the action should deploy.
+          TARGET_FOLDER: ${{ steps.version.outputs.VERSION_NAME }}
+          PRESERVE: true

.gitignore

@@ -1,4 +1,3 @@
-scripts/release/__pycache__
 **/*.o
 **/*bin
 **/*.swp
@@ -7,3 +6,7 @@ tags
 docs/api_doc
 scripts/cppcheck_res.txt
 scripts/built_in_font/lv_font_*
+docs/doxygen_html
+docs/xml
+out_html
+__pycache__

docs/_ext/lv_example.py

@@ -0,0 +1,45 @@
+from docutils.parsers.rst import Directive
+from docutils import nodes
+from docutils.parsers.rst.directives.images import Image
+from sphinx.directives.code import LiteralInclude
+import os
+
+class LvExample(Directive):
+    required_arguments = 3
+    def run(self):
+        example_path = self.arguments[0]
+        example_name = os.path.split(example_path)[1]
+        node_list = []
+
+        env = self.state.document.settings.env
+
+        if self.arguments[2] == 'py':
+            paragraph_node = nodes.raw(text=f"Click to try in the simulator!<br/><a target='_blank' href='https://sim.lvgl.io/v7/micropython/ports/javascript/bundle_out/index.html?script_startup=https://raw.githubusercontent.com/lvgl/lv_examples/{env.config.example_commit_hash}/src/header.py&script=https://raw.githubusercontent.com/lvgl/lv_examples/{env.config.built_example_commit_hash}/{example_name}/{example_name}.py'><img alt='{example_name}' src='https://raw.githubusercontent.com/lvgl/lv_examples/{env.config.built_example_commit_hash}/{example_name}/{example_name}.png'/></a>", format='html')
+        else:
+            paragraph_node = nodes.raw(text=f"<iframe class='lv-example' src='../_static/built_lv_examples/{example_name}/?w=320&h=240'></iframe>", format='html')
+        toggle = nodes.container('', literal_block=False, classes=['toggle'])
+        header = nodes.container('', literal_block=False, classes=['header'])
+        toggle.append(header)
+        example_file = os.path.abspath("lv_examples/src/" + example_path + "." + self.arguments[2])
+
+        with open(example_file) as f:
+            contents = f.read()
+            literal_list = nodes.literal_block(contents, contents)
+            literal_list['language'] = self.arguments[2]
+        toggle.append(literal_list)
+        header.append(nodes.paragraph(text="code"))
+        if env.app.tags.has('html'):
+            node_list.append(paragraph_node)
+        node_list.append(toggle)
+        return node_list
+
+def setup(app):
+    app.add_directive("lv_example", LvExample)
+    app.add_config_value("example_commit_hash", "", "env")
+    app.add_config_value("built_example_commit_hash", "", "env")
+
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

docs/_static/css/custom.css

@@ -0,0 +1,58 @@
+table, th, td {
+  border: 1px solid #bbb;
+  padding: 10px;
+}
+
+td {
+  text-align:center;
+}
+
+.toggle .header {
+    display: block;
+    clear: both;
+    cursor: pointer;
+    font-weight: bold; 
+}
+
+.toggle .header:before {
+   font-family: FontAwesome, "Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;
+   content: "\f0da \00a0 Show "; 
+   display: inline-block;
+   font-size: 1.1em;
+}
+
+.toggle .header.open:before {
+   content: "\f0d7 \00a0 Hide "; 
+}
+
+.header p {
+    display: inline-block;
+    font-size: 1.1em;
+    margin-bottom: 8px;
+}
+
+.wy-side-nav-search {
+  background-color: #f5f5f5;
+}
+.wy-side-nav-search>div.version {
+  color: #333;
+}
+
+
+.home-img {
+  width:32%; 
+  transition: transform .3s ease-out;
+}
+
+.home-img:hover {
+  transform: translate(0, -10px);
+}
+
+.lv-example {
+  border: none;
+  outline: none;
+  padding: none;
+  display: block;
+  width: 320px;
+  height: 240px;
+}

docs/build.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+
+import sys
+import os
+import subprocess
+import re
+
+langs = ['en']
+
+# Change to script directory for consistency
+abspath = os.path.abspath(__file__)
+dname = os.path.dirname(abspath)
+os.chdir(dname)
+
+def cmd(s):
+  print("")
+  print(s)
+  print("-------------------------------------")
+  r = os.system(s)
+  if r != 0: 
+    print("Exit build due to previous error")
+    exit(-1)
+
+# Get the current branch name
+status, br = subprocess.getstatusoutput("git branch | grep '*'")
+br = re.sub('\* ', '', br)
+urlpath = re.sub('release/', '', br)
+ 
+# Be sure the github links point to the right branch
+f = open("header.rst", "w")
+f.write(".. |github_link_base| replace:: https://github.com/lvgl/docs/blob/" + br)
+f.close()
+
+base_html = "html_baseurl = 'https://docs.lvgl.io/" + urlpath + "/en/html/'"
+
+os.system("sed -i \"s|html_baseurl = .*|" + base_html +"|\" conf.py")
+
+clean = 0
+trans = 0
+args = sys.argv[1:]
+if len(args) >= 1:
+  if "clean" in args: clean = 1
+  
+lang = "en"
+print("")
+print("****************")
+print("Building")
+print("****************")
+if clean:
+  cmd("rm -rf " + lang)
+  cmd("mkdir " + lang)
+
+
+print("Running doxygen")
+cmd("cd ../scripts && doxygen Doxyfile")
+# BUILD PDF
+
+# Silly workarond to include the more or less correct PDF download link in the PDF
+#cmd("cp -f " + lang +"/latex/LVGL.pdf LVGL.pdf | true")
+#cmd("sphinx-build -b latex . en/latex")
+
+# Generat PDF
+#cmd("cd " + lang + "/latex && xelatex -interaction=batchmode *.tex")
+# Copy the result PDF to the main diractory to make it avaiable for the HTML build
+#cmd("cd " + lang + "/latex && cp -f LVGL.pdf ../../LVGL.pdf")
+
+# BULD HTML
+cmd("sphinx-build -b html . ../out_html")
+

docs/conf.py

@@ -0,0 +1,254 @@
+#!/usr/bin/env python3.7
+# -*- coding: utf-8 -*-
+#
+# LVGL documentation build configuration file, created by
+# sphinx-quickstart on Wed Jun 12 16:38:40 2019.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# 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
+import subprocess
+sys.path.insert(0, os.path.abspath('./_ext'))
+
+import recommonmark
+from recommonmark.transform import AutoStructify
+from sphinx.builders.html import StandaloneHTMLBuilder
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# 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.intersphinx',
+    'sphinx.ext.todo',
+    'recommonmark',
+    'sphinx_markdown_tables',
+    'breathe',
+    'sphinx_sitemap',
+    'lv_example'
+    ]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The default language to highlight source code in. The default is 'python'. 
+# The value should be a valid Pygments lexer name, see Showing code examples for more details.
+
+
+highlight_language = 'c'
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = ['.rst', '.md']
+
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'LVGL'
+copyright = '2020, LVGL LLC'
+author = 'The community of LVGL'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = 'v7.11.0-dev'
+
+# 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 = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'doxygen_html', 'Thumbs.db', '.DS_Store', 
+                    'README.md', 'lv_examples', 'out_html' ]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+
+# -- 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'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {
+    'collapse_navigation' : False,
+    'logo_only': True,
+}
+# For site map generation
+html_baseurl = 'https://docs.lvgl.io/master/en/html/'
+sitemap_url_scheme = "{link}"
+
+# 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']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    '**': [
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+    ]
+}
+
+html_favicon = 'favicon.png'
+html_logo = 'logo_lvgl.png'
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'LVGLdoc'
+
+html_last_updated_fmt = ''
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+    
+    'inputenc': '',
+    'utf8extra': '',
+    'classoptions': ',openany,oneside',
+    'preamble': r'''
+\usepackage{fontspec}
+\setmonofont{DejaVu Sans Mono}
+\usepackage{xeCJK}
+\setCJKmainfont{SimSun}
+\usepackage{silence}
+\WarningsOff*
+''',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'LVGL.tex', 'LVGL Documentation ' + version,
+     'Contributors of LVGL', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'lvgl', 'LVGL Documentation ' + version,
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'LVGL', 'LVGL Documentation ' + version,
+     author, 'Contributors of LVGL', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+breathe_projects = {
+  "lvgl":"xml/",
+}
+
+StandaloneHTMLBuilder.supported_image_types = [
+    'image/svg+xml',
+    'image/gif',  #prefer gif over png
+    'image/png',
+    'image/jpeg'
+]
+
+smartquotes = False
+
+# Example configuration for intersphinx: refer to the Python standard library.
+
+def setup(app):
+    app.add_config_value('recommonmark_config', {
+            'enable_eval_rst': True,
+            'enable_auto_toc_tree': 'True',
+            }, True)
+    app.add_transform(AutoStructify)
+    app.add_stylesheet('css/custom.css')
+    app.add_stylesheet('css/fontawesome.min.css')
+
+# Attempt to checkout _static/built_lv_examples
+
+
+"""
+if not os.path.exists('_static/built_lv_examples'):
+    os.system('git clone https://github.com/lvgl/lv_examples.git _static/built_lv_examples')
+
+os.system('git -C _static/built_lv_examples fetch origin')
+
+out = subprocess.Popen(["git", "-C", "lv_examples", "rev-parse", "HEAD"], 
+       stdout=subprocess.PIPE, 
+       stderr=subprocess.STDOUT)
+stdout,stderr = out.communicate()
+example_commit_hash = stdout.decode("utf-8").strip()
+
+search_command = ["git", "-C", "_static/built_lv_examples", "--no-pager", "log", "--pretty=format:'%H'", "--all", "-n", "1", f"--grep='Deploying to gh-pages from  @ {example_commit_hash}'"]
+log_output = subprocess.check_output(' '.join(search_command), shell=True).strip().decode("utf-8")
+if len(log_output) == 0:
+    raise ValueError('lv_examples: cannot find corresponding deployed commit: ' + example_commit_hash)
+
+built_example_commit_hash = log_output
+os.system('git -C _static/built_lv_examples reset --hard')
+os.system('git -C _static/built_lv_examples checkout ' + log_output)
+ """

docs/header.rst

@@ -0,0 +1 @@
+.. |github_link_base| replace:: https://github.com/lvgl/docs/blob/master

docs/index.md

@@ -0,0 +1,37 @@
+```eval_rst
+.. include:: /header.rst 
+:github_url: |github_link_base|/index.md
+```
+
+```eval_rst
+.. include:: /lang.rst
+
+```
+
+# Welcome to the documentation of LVGL!
+
+<img src="_static/img/home_banner.jpg" style="width:100%">
+
+
+<div style="margin-bottom:48px"> 
+    <a href="intro/index.html"><img class="home-img" src="_static/img/home_1.png" alt="Get familiar with the LVGL project"></a>
+    <a href="get-started/index.html"><img class="home-img" src="_static/img/home_2.png" alt="Learn the basic of LVGL and its usage on various platforms"></a>
+    <a href="porting/index.html"><img class="home-img" src="_static/img/home_3.png" alt="See how to port LVGL to any platform"></a>
+    <a href="overview/index.html"><img class="home-img" src="_static/img/home_4.png" alt="Learn the how LVGL works in more detail"></a>
+    <a href="widgets/index.html"><img class="home-img" src="_static/img/home_5.png" alt="Take a look at the description of the available widgets"></a>
+    <a href="contributing/index.html"><img class="home-img" src="_static/img/home_6.png" alt="Be part of the development of LVGL"></a>
+</div> 
+ 
+
+```eval_rst
+.. toctree::
+   :maxdepth: 2
+   
+   intro/index
+   get-started/index
+   porting/index
+   overview/index
+   widgets/index
+   contributing/index
+
+```

scripts/Doxyfile

@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = ../docs/api_doc
+OUTPUT_DIRECTORY       = ../docs
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -1091,7 +1091,7 @@ GENERATE_HTML          = YES
 # The default directory is: html.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_OUTPUT            = html
+HTML_OUTPUT            = doxygen_html
 
 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
 # generated HTML page (for example: .htm, .php, .asp).

scripts/find_version.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+# Credit: https://stackoverflow.com/a/4774063
+SCRIPTPATH="$( cd -- "$(dirname "$0")" >/dev/null 2>&1 ; pwd -P )"
+TMPENVFILE=$(mktemp /tmp/lvgl.script.XXXXXX)
+cat $SCRIPTPATH/../lvgl.h | grep "#define LVGL_VERSION_" | sed 's/#define //g' | sed -r 's/\s+/=/' > $TMPENVFILE
+. $TMPENVFILE
+rm $TMPENVFILE
+echo $LVGL_VERSION_MAJOR.$LVGL_VERSION_MINOR