Create initial publication

.github/workflows/main.yml

@@ -0,0 +1,30 @@
+name: documentation
+
+on:
+  push:
+    branches:
+      - 'publish'
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+      - name: Install dependencies
+        run: |
+          pip install sphinx sphinx_rtd_theme myst_parser
+      - name: Sphinx build
+        run: |
+          sphinx-build docs _build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/
+          force_orphan: true

.gitignore

@@ -1,2 +1,17 @@
-venv/
+# This .gitignore file is intended to be minimal.
+#
+# If you find that you need additional rules, such as IDE temporary
+# files, please do so either via a global .gitignore file (registered
+# with core.excludesFile), or by adding private repository-specific
+# rules to .git/info/exclude.  See https://git-scm.com/docs/gitignore
+# for more information.
+
+# Build directories
 build/
+build-*/
+docs/genrst/
+
+# Python cache files
+__pycache__/
+
+venv/

README.md

@@ -0,0 +1,2 @@
+# DisplayLink DL-7450 SDK Documentation and Samples
+This repository contains examples and documentation of the DisplayLink DL-7450 SDK

docs/Makefile

@@ -0,0 +1,36 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+PYTHON        = python3
+SPHINXOPTS    = -W --keep-going -j auto
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build/
+GENRSTDIR     = genrst
+# Run "make FORCE= ..." to avoid rebuilding from scratch (and risk
+# producing incorrect docs).
+FORCE         = -E
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+	rm -f $(GENRSTDIR)/*
+
+html:
+	$(SPHINXBUILD) $(FORCE) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+

docs/README.md

@@ -0,0 +1,4 @@
+DL-7450 SDK Documentation
+=========================
+
+This is the source code for the DL-7450 SDK documentation pages.

docs/conf.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# MicroPython documentation build configuration file, created by
+# sphinx-quickstart on Sun Sep 21 11:42:03 2014.
+#
+# 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.
+
+import sys
+import os
+
+# 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.
+sys.path.insert(0, os.path.abspath("."))
+
+# The DL_7450_VERSION env var should be "vX.Y.Z" (or unset).
+dl7450_version = os.getenv("DL_7450_VERSION") or "latest"
+dl7450_all_versions = (os.getenv("DL_7450_ALL_VERSIONS") or "latest").split(",")
+url_pattern = "%s/en/%%s" % (os.getenv("DL_7450_URL_PREFIX") or "/",)
+
+# The members of the html_context dict are available inside topindex.html
+html_context = {
+    "cur_version": dl7450_version,
+    "all_versions": [(ver, url_pattern % ver) for ver in dl7450_all_versions],
+    "is_release": dl7450_version != "latest",
+}
+
+
+# -- 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.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
+    "sphinxcontrib.jquery",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["templates"]
+
+# The suffix of source filenames.
+source_suffix = ".rst"
+
+# The encoding of source files.
+# source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = "index"
+
+# General information about the project.
+project = "DisplayLink DL-7450 SDK"
+copyright = "- The DisplayLink DL-7450 SDK is Copyright © 2024 Synaptics Inc."
+version = release = dl7450_version
+
+exclude_patterns = ["build", ".venv", "venv"]
+
+default_role = "any"
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+# add_module_names = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# Global include files. Sphinx docs suggest using rst_epilog in preference
+# of rst_prolog, so we follow. Absolute paths below mean "from the base
+# of the doctree".
+rst_epilog = """
+.. include:: /templates/replace.inc
+"""
+
+# -- Options for HTML output ----------------------------------------------
+
+# on_rtd is whether we are on readthedocs.org
+on_rtd = os.environ.get("READTHEDOCS", None) == "True"
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    try:
+        import sphinx_rtd_theme
+
+        html_theme = "sphinx_rtd_theme"
+        html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), "."]
+    except:
+        html_theme = "default"
+        html_theme_path = ["."]
+else:
+    html_theme_path = ["."]
+
+# 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 = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = ['.']
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+# html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+# html_logo = '../../logo/trans-logo.png'
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+html_favicon = "static/favicon.ico"
+
+# 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"]
+
+# Add a custom CSS file for HTML generation
+html_css_files = [
+    "custom.css",
+]
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+# html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = "%d %b %Y"
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+html_additional_pages = {"index": "topindex.html"}
+
+# If false, no module index is generated.
+# html_domain_indices = True
+
+# If false, no index is generated.
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+# html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+# html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+# html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+# html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "DL7450doc"
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {"python": ("https://docs.python.org/3.5", None)}

docs/index.rst

@@ -0,0 +1,5 @@
+DisplayLink DL-7450 SDK documentation and references
+====================================================
+
+.. toctree::
+

docs/readthedocs/settings/local_settings.py

@@ -0,0 +1,10 @@
+import os
+
+# Directory that the project lives in, aka ../..
+SITE_ROOT = "/".join(os.path.dirname(__file__).split("/")[0:-2])
+
+TEMPLATE_DIRS = (
+    "%s/templates/"
+    % SITE_ROOT,  # Your custom template directory, before the RTD one to override it.
+    "%s/readthedocs/templates/" % SITE_ROOT,  # Default RTD template dir
+)

docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinx~=7.2.6
+sphinx_rtd_theme
+sphinxcontrib.jquery==4.1

docs/static/custom.css

@@ -0,0 +1,5 @@
+/* Workaround to force Sphinx to render tables to 100% and wordwrap */
+/* See https://stackoverflow.com/questions/69359978/grid-table-does-not-word-wrap for more details */
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: inherit;
+}

docs/static/customstyle.css

@@ -0,0 +1,8 @@
+.admonition-difference-to-cpython {
+    border: 1px solid black;
+}
+
+.admonition-difference-to-cpython .admonition-title {
+    margin: 4px;
+}
+

docs/templates/layout.html

@@ -0,0 +1,25 @@
+{% extends "!layout.html" %}
+{% set css_files = css_files + ["_static/customstyle.css"] %}
+
+{% set master_doc = "index" %}
+
+{% block document %}
+  {% if is_release %}
+    <div class="wy-alert wy-alert-danger">
+      <p>
+        This is the {{ release }} version of the DisplayLink DL-7450 SDK
+        documentation.
+      </p>
+    </div>
+  {% else %}
+    <div class="wy-alert wy-alert-danger">
+      <p>
+			  Coming soon: a preview version of the DisplayLink DL-7450 Software Development Kit.
+				These pages will contain a guide, references and sample code.
+      </p>
+      <p>
+      </p>
+    </div>
+  {% endif %}
+  {{ super() }}
+{% endblock %}

docs/templates/replace.inc

@@ -0,0 +1,2 @@
+.. comment: This file is intended for global "replace" definitions.
+

docs/templates/topindex.html

@@ -0,0 +1,11 @@
+{% extends "layout.html" %}
+{% set title = _('Overview') %}
+{% block body %}
+
+  <h1>DisplayLink DL-7450 Software Development Kit</h1>
+
+  <p>
+    {{ _('Welcome to the DisplayLink DL-7450 SDK documentation.') }}
+  </p>
+
+{% endblock %}

docs/templates/versions.html

@@ -0,0 +1,28 @@
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    <span class="fa fa-book"> Versions and Downloads</span>
+    {{ cur_version }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    <dl>
+      <dt>Versions</dt>
+      {% for slug, url in all_versions %}
+        <dd><a href="{{ url }}">{{ slug }}</a></dd>
+      {% endfor %}
+    </dl>
+    <dl>
+      <dt>Downloads</dt>
+      {% for type, url in downloads %}
+        <dd><a href="{{ url }}">{{ type }}</a></dd>
+      {% endfor %}
+    </dl>
+    <hr/>
+    <dl>
+      <dt>External links</dt>
+        <dd>
+          <a href="https://github.com/DisplayLink/dl-7450">GitHub</a>
+        </dd>
+    </dl>
+  </div>
+</div>