Move the documentation for each example into sphinx docs and improve it

.flake8

@@ -14,7 +14,6 @@ exclude =
     __pycache__,
     venv,
     build,
-    docs/source/conf.py,
     workspace,
 count = True
 show-source = True

.github/scripts/ci.sh

@@ -6,7 +6,7 @@ set -e
 set -o pipefail
 
 ROOT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")"/../.. &>/dev/null && pwd)
-EXAMPLES=(hdmi inout pwm soc hierarchy)
+EXAMPLES=(constant hdmi inout pwm soc)
 
 begin_command_group() {
     if [[ -n "${GITHUB_WORKFLOW:-}" ]]; then
@@ -83,12 +83,6 @@ install_nox() {
     end_command_group
 }
 
-install_tuttest(){
-    begin_command_group "Installing tuttest"
-    log_cmd pip install git+https://github.com/antmicro/tuttest
-    end_command_group
-}
-
 install_pyenv() {
     begin_command_group "Install pyenv"
     log_cmd apt-get install -y --no-install-recommends \
@@ -134,7 +128,6 @@ run_python_tests() {
 generate_examples() {
     install_common_system_packages
     install_topwrap_system_deps
-    install_tuttest
 
     begin_command_group "Installing Topwrap"
     log_cmd pip install "."
@@ -143,7 +136,7 @@ generate_examples() {
     for EXAMPLE in "${EXAMPLES[@]}"; do
         begin_command_group "Generate $EXAMPLE example"
         log_cmd pushd "$ROOT_DIR"/examples/"$EXAMPLE"
-        log_cmd "tuttest README.md install-deps,generate | bash -"
+        log_cmd make ci
         log_cmd popd
         end_command_group
     done
@@ -152,6 +145,7 @@ generate_examples() {
 
 generate_docs() {
     install_common_system_packages
+    install_topwrap_system_deps
     begin_command_group "Install system packages for doc generation"
     log_cmd apt-get install -y texlive-full make
     end_command_group

docs/source/conf.py

@@ -13,11 +13,12 @@
 # Updated documentation of the configuration options is available at
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-from datetime import datetime
-from os import environ
 import os
 import sys
+from datetime import datetime
+from os import environ
 
+from antmicro_sphinx_utils.defaults import numfig_format  # noqa: F401
 from antmicro_sphinx_utils.defaults import antmicro_html, antmicro_latex
 from antmicro_sphinx_utils.defaults import extensions as default_extensions
 from antmicro_sphinx_utils.defaults import (
@@ -26,71 +27,60 @@
 from antmicro_sphinx_utils.defaults import (
     myst_fence_as_directive as default_myst_fence_as_directive,
 )
-from antmicro_sphinx_utils.defaults import numfig_format
 
 # 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('./_extensions'))
+sys.path.insert(0, os.path.abspath("./_extensions"))
 
 # -- General configuration -----------------------------------------------------
 
 # General information about the project.
-project = u'Topwrap'
-basic_filename = u'topwrap'
-authors = u'Antmicro'
-copyright = f'{authors}, {datetime.now().year}'
+project = "Topwrap"
+basic_filename = "topwrap"
+authors = "Antmicro"
+copyright = f"{authors}, {datetime.now().year}"
 
 # The short X.Y version.
-version = ''
+version = ""
 # The full version, including alpha/beta/rc tags.
-release = ''
+release = ""
 
 # This is temporary before the clash between myst-parser and immaterial is fixed
 sphinx_immaterial_override_builtin_admonitions = False
 
 numfig = True
 
 # If you need to add extensions just add to those lists
-extensions = list(set(default_extensions + [
-    'sphinx.ext.autodoc', 'kpm_plugin'
-]))
+extensions = list(set(default_extensions + ["sphinx.ext.autodoc", "kpm_plugin"]))
 myst_enable_extensions = default_myst_enable_extensions
 myst_fence_as_directive = default_myst_fence_as_directive
 
-myst_substitutions = {
-    "project": project
-}
+myst_substitutions = {"project": project}
+
 
-today_fmt = '%Y-%m-%d'
+today_fmt = "%Y-%m-%d"
 
-todo_include_todos=False
+todo_include_todos = False
 
 # -- Options for HTML output ---------------------------------------------------
 
-html_theme = 'sphinx_immaterial'
+html_theme = "sphinx_immaterial"
 
 html_last_updated_fmt = today_fmt
 
 html_show_sphinx = False
 
 html_title = project
 
-(
-    html_logo,
-    html_theme_options,
-    html_context
-) = antmicro_html(
-    gh_slug=environ.get('GITHUB_REPOSITORY', 'antmicro/topwrap'),
+(html_logo, html_theme_options, html_context) = antmicro_html(
+    gh_slug=environ.get("GITHUB_REPOSITORY", "antmicro/topwrap"),
     pdf_url=f"{basic_filename}.pdf",
 )
 
-(
-    latex_elements,
-    latex_documents,
-    latex_logo,
-    latex_additional_files
-) = antmicro_latex(basic_filename, authors, project)
+(latex_elements, latex_documents, latex_logo, latex_additional_files) = antmicro_latex(
+    basic_filename, authors, project
+)
 
 # prevent rendering full class names in automatically generated docs,
 # e.g. render "IPConnect" instead of "topwrap.ipconnect.IPConnect"