LcdMenu 5.0.0 Documentation

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Build and Deploy Docs
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - "src/**"
+      - "docs/**"
+      - "examples/**"
+      - ".scripts/**"
+      - ".github/workflows/docs.yml"
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.x"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+          sudo apt-get update
+          sudo apt-get install -y doxygen graphviz default-jre plantuml
+
+      - name: Pre-build
+        run: |
+          chmod +x docs/pre_build.bat
+          docs/pre_build.bat
+
+      - name: Generate Sphinx documentation
+        run: make html
+        working-directory: docs
+        env:
+          GITHUB_ACTIONS: true
+
+      - name: Deploy documentation
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/_build/html

.gitignore

@@ -9,4 +9,7 @@ _site/
 .jekyll-cache/
 .arduino_ci/
 *.tar.gz
-*.lock
+*.lock
+_build/
+docs/doxygen/
+docs/source/reference/api

.readthedocs.yml

@@ -0,0 +1,30 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+  apt_packages:
+    - doxygen
+    - graphviz
+    - default-jre
+    - plantuml
+  jobs:
+    pre_build:
+      - chmod +x docs/pre_build.bat
+      - docs/pre_build.bat
+
+sphinx:
+  configuration: docs/source/conf.py
+
+formats:
+  - pdf
+  - epub
+
+python:
+  install:
+    - requirements: docs/requirements.txt

.scripts/append_includes.py

@@ -0,0 +1,56 @@
+import os
+import re
+import sys
+
+
+def replace_includes(directory, sort_order='asc', use_toctree=False):
+    include_pattern = re.compile(r'\.\. include::\s+\S+')
+    toctree_pattern = re.compile(r'\.\. toctree::\s+.*?(\n\s+.*?)*', re.DOTALL)
+    maxdepth_pattern = re.compile(r':maxdepth:\s+\d+')
+    rst_file_pattern = re.compile(r'^\s+\S+\.rst$', re.MULTILINE)
+
+    for root, _, files in os.walk(directory):
+        if 'index.rst' in files:
+            index_path = os.path.join(root, 'index.rst')
+            print(f"Processing {index_path}")
+            with open(index_path, 'r') as index_file:
+                content = index_file.read()
+
+            # Remove existing include, toctree, maxdepth, and rst file directives
+            content = include_pattern.sub('', content)
+            content = toctree_pattern.sub('', content)
+            content = maxdepth_pattern.sub('', content)
+            content = rst_file_pattern.sub('', content).strip()
+
+            rst_files = [file for file in files if file.endswith('.rst') and file != 'index.rst']
+            rst_files.sort(reverse=(sort_order == 'desc'))
+
+            if use_toctree:
+                content += '\n\n.. toctree::\n   :maxdepth: 2\n\n'
+                for file in rst_files:
+                    content += f'   {file}\n'
+                    print(f"Added {file} to toctree")
+            else:
+                content += '\n'
+                for file in rst_files:
+                    content += f'\n.. include:: {file}'
+                    print(f"Added include directive for {file}")
+
+            with open(index_path, 'w') as index_file:
+                index_file.write(content.strip() + '\n')
+            print(f"Updated {index_path}")
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2 or len(sys.argv) > 4:
+        print("Usage: python append_includes.py <directory_path> [sort_order] [use_toctree]")
+        sys.exit(1)
+
+    directory_path = sys.argv[1]
+    sort_order = sys.argv[2] if len(sys.argv) >= 3 else 'asc'
+    use_toctree = sys.argv[3].lower() == 'true' if len(sys.argv) == 4 else False
+
+    if sort_order not in ['asc', 'desc']:
+        print("Invalid sort order. Use 'asc' for ascending or 'desc' for descending.")
+        sys.exit(1)
+
+    replace_includes(directory_path, sort_order, use_toctree)

.scripts/keywords.py

@@ -46,7 +46,7 @@ def build(files):
                     if re.search(r"^.+\s[a-z][A-Za-z]+\(.*", stripped_line) != None:
                         words = re.findall(r"\w+", stripped_line)
                         methodName = words[1]
-                        if words[0] == 'const':
+                        if words[0] == 'const' or words[0] == 'inline':
                             methodName = words[2]
                         keyword_2_data.add(methodName + "	KEYWORD2\n")
                 if len(stripped_line) > 7 and stripped_line.startswith('class '):
@@ -61,11 +61,11 @@ def build(files):
     with open("keywords.txt", "w") as a_file:
         a_file.truncate()
         a_file.write(pre_key_1)
-        a_file.writelines(keyword_1_data)
+        a_file.writelines(sorted(keyword_1_data))
         a_file.write(pre_key_2)
-        a_file.writelines(keyword_2_data)
+        a_file.writelines(sorted(keyword_2_data))
         a_file.write(pre_lit_1)
-        a_file.writelines(literal_1_data)
+        a_file.writelines(sorted(literal_1_data))
         print("Updated keywords")
 
 if __name__ == '__main__':

.scripts/link_doxygen_sphinx.py

@@ -0,0 +1,57 @@
+import os
+
+src_dir = 'src'
+dest_dir = 'docs/source/reference/api'
+skip_files = []
+skip_dirs = ['utils']
+
+def create_rst_file(src_path, dest_path):
+    os.makedirs(os.path.dirname(dest_path), exist_ok=True)
+    filename = os.path.basename(src_path).replace('.h', '')
+    with open(dest_path, 'w') as rst_file:
+        rst_file.write(f'{filename}\n')
+        rst_file.write(f'{"=" * len(filename)}\n\n')
+        rst_file.write(f'.. doxygenfile:: {filename}.h\n')
+        rst_file.write(f'   :project: LcdMenu\n')
+
+def create_index_file(directory, entries, subdirs, is_root=False):
+    dir_name = os.path.basename(directory) if not is_root else "API reference"
+    index_path = os.path.join(directory, 'index.rst')
+    with open(index_path, 'w') as index_file:
+        index_file.write(f'{dir_name}\n')
+        index_file.write(f'{"=" * len(dir_name)}\n\n')
+        if is_root:
+            index_file.write('.. rst-class:: lead\n\n')
+            index_file.write('This section contains the API reference documentation for the |project| library.\n')
+            index_file.write('Here you will find detailed descriptions of all the classes, their methods, and attributes.\n\n')
+            index_file.write('-'*80)
+            index_file.write('\n\n')
+        index_file.write('.. toctree::\n')
+        index_file.write('   :maxdepth: 1\n')
+        index_file.write(f'   :caption: {dir_name}\n\n')
+        for entry in entries:
+            relative_entry = os.path.relpath(entry, directory).replace('.rst', '')
+            index_file.write(f'   {relative_entry}\n')
+        for subdir in subdirs:
+            relative_subdir = os.path.basename(subdir)
+            index_file.write(f'   {relative_subdir}/index\n')
+
+def process_directory(directory, skip_files, skip_dirs, is_root=False):
+    for root, dirs, files in os.walk(directory):
+        dirs[:] = [d for d in dirs if d not in skip_dirs]
+
+        index_entries = []
+        subdirs = [os.path.join(root, d) for d in dirs]
+        for file in files:
+            if file.endswith('.h') and file not in skip_files:
+                src_path = os.path.relpath(os.path.join(root, file), src_dir)
+                dest_path = os.path.join(dest_dir, src_path).replace('.h', '.rst')
+                create_rst_file(src_path, dest_path)
+                index_entries.append(dest_path)
+
+        if index_entries or subdirs:
+            create_index_file(os.path.join(dest_dir, os.path.relpath(root, src_dir)), index_entries, subdirs, is_root)
+            is_root = False
+
+if __name__ == '__main__':
+    process_directory(src_dir, skip_files, skip_dirs, is_root=True)

.scripts/link_examples_sphinx.py

@@ -0,0 +1,57 @@
+import os
+
+src_dir = 'examples'
+dest_dir = 'docs/source/reference/samples'
+skip_files = []
+skip_dirs = []
+
+def create_rst_file(src_path, dest_path):
+    os.makedirs(os.path.dirname(dest_path), exist_ok=True)
+    filename = os.path.basename(src_path).replace('.ino', '')
+    with open(dest_path, 'w') as rst_file:
+        rst_file.write(f'{filename}\n')
+        rst_file.write(f'{"=" * len(filename)}\n\n')
+        rst_file.write(f'.. literalinclude:: ../../../../{src_dir}/{src_path}\n')
+        rst_file.write(f'   :language: cpp\n')
+        rst_file.write(f'   :linenos:\n\n')
+
+def create_index_file(directory, entries):
+    dir_name = "Code samples"
+    index_path = os.path.join(directory, 'index.rst')
+    os.makedirs(os.path.dirname(index_path), exist_ok=True)
+    with open(index_path, 'w') as index_file:
+        index_file.write(f'{dir_name}\n')
+        index_file.write(f'{"=" * len(dir_name)}\n\n')
+        index_file.write('.. rst-class:: lead\n\n')
+        index_file.write('This section contains code samples that demonstrate how to use the |project| library.\n')
+        index_file.write('Each sample is a complete program that shows how to use the library to accomplish a specific task.\n')
+        index_file.write('You can find the source code for each sample in the `examples <https://github.com/forntoh/LcdMenu/tree/master/examples>`_ directory of the library repository.\n\n')
+        index_file.write('-'*80)
+        index_file.write('\n\n')
+        index_file.write('.. toctree::\n')
+        index_file.write('   :maxdepth: 1\n')
+        index_file.write(f'   :caption: {dir_name}\n\n')
+        for entry in entries:
+            print(entry)
+            relative_entry = os.path.relpath(entry, directory).replace('.rst', '')
+            index_file.write(f'   {relative_entry}\n')
+
+def process_directory(directory, skip_files, skip_dirs):
+    index_entries = []
+
+    for root, dirs, files in os.walk(directory):
+        dirs[:] = [d for d in dirs if d not in skip_dirs]
+
+        for file in files:
+            if file.endswith('.ino') and file not in skip_files:
+                src_path = os.path.relpath(os.path.join(root, file), src_dir)
+                dest_path = os.path.join(dest_dir, os.path.basename(file)).replace('.ino', '.rst')
+                create_rst_file(src_path, dest_path)
+                print(f'Created {dest_path}')
+                index_entries.append(dest_path)
+
+    if index_entries:
+        create_index_file(dest_dir, index_entries)
+
+if __name__ == '__main__':
+    process_directory(src_dir, skip_files, skip_dirs)

.scripts/update_changelog.py

@@ -0,0 +1,56 @@
+import re
+
+import requests
+
+GITHUB_API_URL = "https://api.github.com/repos/{owner}/{repo}/releases"
+OWNER = "forntoh"
+REPO = "LcdMenu"
+CHANGELOG_FILE = "docs/source/reference/changelog.rst"
+
+def fetch_releases():
+    url = GITHUB_API_URL.format(owner=OWNER, repo=REPO)
+    response = requests.get(url)
+    response.raise_for_status()
+    return response.json()
+
+def convert_md_to_rst(body):
+    lines = body.split('\n')
+    rst_lines = []
+    for line in lines:
+        if line.startswith('## '):
+            heading = line[3:]
+            rst_lines.append(heading)
+            rst_lines.append('~' * len(heading))
+        elif line.startswith('### '):
+            heading = line[4:]
+            rst_lines.append(heading)
+            rst_lines.append('+' * len(heading))
+        else:
+            line = re.sub(r'(https://github\.com/forntoh/LcdMenu/pull/(\d+))', r'`#\2 <\1>`_', line)
+            rst_lines.append(line)
+    return '\n'.join(rst_lines)
+
+def format_release(release):
+    body = convert_md_to_rst(release['body'])
+    return f"{release['name']}\n{'-' * len(release['name'])}\n\n{body}\n"
+
+
+def update_changelog(releases):
+    with open(CHANGELOG_FILE, 'r') as file:
+        lines = file.readlines()
+
+    with open(CHANGELOG_FILE, 'w') as file:
+        for line in lines:
+            if line.strip() == "----------------":
+                break
+            file.write(line)
+
+        file.write("\n")
+        for release in releases:
+            file.write(format_release(release))
+            print(f"Added release: {release['name']}")
+            file.write("\n")
+
+if __name__ == "__main__":
+    releases = fetch_releases()
+    update_changelog(releases)

.scripts/version.py

@@ -13,14 +13,19 @@ def build(files, version):
         data = ''
         separator = ''
         if file.endswith('.json'): separator = ": "
+        elif file.endswith('.rst'): separator = '^'
         else: separator = '='
 
         with open(file, "r") as a_file:
             for line in a_file:
                 stripped_line = line.strip()
                 key = stripped_line.split(separator, 1)[0]
 
-                if re.search("version", key) != None:
+
+                if separator == '^' and re.search("forntoh/LcdMenu", key) != None:
+                    spaces = len(line) - len(line.lstrip())
+                    data+=(' ' * spaces + key + separator + version + '\n')
+                elif re.search("version", key) != None:
                     anchor = ''
                     suffix = ''
                     prefix = ''

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020-2023 Forntoh Thomas
+Copyright (c) 2020-2024 Forntoh Thomas
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal