docs: Use mkdocs for public documentation (#2527)
* Add mkdocs config Build and debug docs locally: mkdocs serve * Add mkdocs config * Introduce GitHub action for mkdocs * Delete outdated doc files * Generate Python documentation * Clean up docs - Remove ToDos from public docs
This commit is contained in:
MattHag
GitHub
parent
f40a5cc7a9
commit
59b30706b8
|
|
@ -0,0 +1,53 @@
|
|||
name: Deploy to GitHub Pages
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
- '*doc*'
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
concurrency:
|
||||
group: 'pages'
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: '3.x'
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip install mkdocs mkdocs-rtd-dropdown mkdocs-mermaid2-plugin mkdocstrings[python]
|
||||
|
||||
- name: Build and deploy
|
||||
run: |
|
||||
mkdocs build
|
||||
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: 'site'
|
||||
|
||||
deploy:
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
|
||||
steps:
|
||||
- name: Deploy to GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v4
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
title: Solaar
|
||||
description: Linux Device Manager for Logitech Unifying Receivers and Devices.
|
||||
tagline: Linux Device Manager for Logitech Unifying Receivers and Devices.
|
||||
owner: pwr-Solaar
|
||||
owner_url: https://github.com/pwr-Solaar
|
||||
repository: pwr-Solaar/Solaar
|
||||
show_downloads: false
|
||||
encoding: utf-8
|
||||
theme: jekyll-theme-slate
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="{{ site.lang | default: "en-US" }}">
|
||||
|
||||
<head>
|
||||
<meta charset='utf-8'>
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width,maximum-scale=2">
|
||||
<link rel="stylesheet" type="text/css" media="screen" href="{{ '/assets/css/style.css?v=' | append: site.github.build_revision | relative_url }}">
|
||||
<link rel="icon" type="image/png" href="{{ site.baseurl }}/assets/favicon.png" />
|
||||
|
||||
{% seo %}
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<!-- HEADER -->
|
||||
<div id="header_wrap" class="outer">
|
||||
<header class="inner">
|
||||
{% if site.github.is_project_page %}
|
||||
<a id="forkme_banner" href="{{ site.github.repository_url }}">View on GitHub</a>
|
||||
{% endif %}
|
||||
<h1 id="project_title">
|
||||
<img src="{{ site.baseurl }}/assets/solaar.svg" style="margin-bottom: -10px; width: 48px; height: 48px; border: 0; box-shadow: none;" />
|
||||
{{ site.title | default: site.github.repository_name }}</h1>
|
||||
<h2 id="project_tagline">{{ site.description | default: site.github.project_tagline }}</h2>
|
||||
|
||||
{% if site.show_downloads %}
|
||||
<section id="downloads">
|
||||
<a class="zip_download_link" href="{{ site.github.zip_url }}">Download this project as a .zip file</a>
|
||||
<a class="tar_download_link" href="{{ site.github.tar_url }}">Download this project as a tar.gz file</a>
|
||||
</section>
|
||||
{% endif %}
|
||||
</header>
|
||||
</div>
|
||||
|
||||
<!-- MAIN CONTENT -->
|
||||
<div id="main_content_wrap" class="outer">
|
||||
<section id="main_content" class="inner">
|
||||
{{ content }}
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<!-- FOOTER -->
|
||||
<div id="footer_wrap" class="outer">
|
||||
<footer class="inner">
|
||||
{% if site.github.is_project_page %}
|
||||
<p class="copyright">{{ site.title | default: site.github.repository_name }} maintained by <a href="{{ site.github.owner_url }}">{{ site.github.owner_name }}</a></p>
|
||||
{% endif %}
|
||||
<p>Published with <a href="https://pages.github.com">GitHub Pages</a></p>
|
||||
</footer>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="{{ site.lang | default: "en-US" }}">
|
||||
|
||||
<head>
|
||||
<meta charset='utf-8'>
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width,maximum-scale=2">
|
||||
<link rel="stylesheet" type="text/css" media="screen" href="{{ '/assets/css/style.css?v=' | append: site.github.build_revision | relative_url }}">
|
||||
<link rel="icon" type="image/png" href="{{ site.baseurl }}/assets/favicon.png" />
|
||||
{% seo %}
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<!-- HEADER -->
|
||||
<div id="header_wrap" class="outer">
|
||||
<header class="inner">
|
||||
{% if site.github.is_project_page %}
|
||||
<a id="forkme_banner" href="{{ site.github.repository_url }}">View on GitHub</a>
|
||||
{% endif %}
|
||||
|
||||
<h1 id="project_title">
|
||||
<a href="{{ site.baseurl }}" style="color: #fff;">
|
||||
<img src="{{ site.baseurl }}/assets/solaar.svg" style="margin-bottom: -10px; width: 48px; height: 48px; border: 0; box-shadow: none;" />
|
||||
{{ site.title | default: site.github.repository_name }}</h1>
|
||||
</a>
|
||||
</header>
|
||||
</div>
|
||||
|
||||
<!-- MAIN CONTENT -->
|
||||
<div id="main_content_wrap" class="outer">
|
||||
<section id="main_content" class="inner">
|
||||
{{ content }}
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<!-- FOOTER -->
|
||||
<div id="footer_wrap" class="outer">
|
||||
<footer class="inner">
|
||||
{% if site.github.is_project_page %}
|
||||
<p class="copyright">{{ site.title | default: site.github.repository_name }} maintained by <a href="{{ site.github.owner_url }}">{{ site.github.owner_name }}</a></p>
|
||||
{% endif %}
|
||||
<p>Published with <a href="https://pages.github.com">GitHub Pages</a></p>
|
||||
</footer>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -80,7 +80,7 @@ that they were bought with.
|
|||
## Device Settings
|
||||
|
||||
Solaar can display quite a few changeable settings of receivers and devices.
|
||||
For a list of HID++ features and their support see [the features page](features).
|
||||
For a list of HID++ features and their support see [the features page](features.md).
|
||||
|
||||
Solaar does not do much beyond using the HID++ protocol to change the
|
||||
behavior of receivers and devices via changing their settings.
|
||||
|
|
|
|||
|
Before Width: | Height: | Size: 1.7 KiB After Width: | Height: | Size: 1.7 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.7 KiB |
|
Before Width: | Height: | Size: 3.7 KiB After Width: | Height: | Size: 3.7 KiB |
|
|
@ -3,8 +3,6 @@ title: Solaar Implementation
|
|||
layout: page
|
||||
---
|
||||
|
||||
TODO: improve the callback mechanism(s) to support the explicit calls of the UI
|
||||
|
||||
# Solaar Implementation
|
||||
|
||||
Solaar has three main components: code mostly about receivers and devices, code for the command line interface, and code for the graphical user interface.
|
||||
|
|
@ -88,8 +86,6 @@ The module `descriptors` sets up information on device models for which Solaar n
|
|||
|
||||
The module `base_usb` sets up information for most of the receiver models that Solaar supports, including USB id, USB interface used for HID++ messages, what kind of receiver model it is, and some capabilities of the receiver model. Solaar can now support other receivers as long as they are not too unusual. The module lso sets up lists of device models by USB ID and Bluetooth ID and provides a function to determine whether a USB ID or Bluetooth ID is an HID++ device model
|
||||
|
||||
TODO? Move some information down to descriptors?
|
||||
|
||||
The module `base` provides functions that call discovery to enumerate all current receivers and devices and to set up a callback for when new receivers or devices are discovered. It provides functions to open and close I/O channels to receivers and devices, write HID++ messages to receivers and devices, and read HID++ messages from receivers and devices. It provides a function to turn an HID++ message into a notification.
|
||||
|
||||
The module provides a function to send an HID++ message to a receiver or device, constructing the message from parameters to the function, and optionally waiting for and returning a response. The function checks messages from the receiver or device, only terminating at timeout or when a message that appears to be the response is seen. Other messages are turned into notifications if appropriate and ignoreed otherwise. A separate function sends a ping message and waits for a reply to the ping.
|
||||
|
|
@ -109,8 +105,6 @@ After this processing HID++ 2.0 notifications are sent to the `diversion` module
|
|||
|
||||
The `status` module provides the `DeviceStatus` class to record the battery status of a device. It also provides an interface to signal changes to the connection status of the device that can invoke a callback. This callback is used to update the Solaar user interface when the status changes.
|
||||
|
||||
TODO: check why solaar/listener.py sets the callback multiple times
|
||||
|
||||
|
||||
### Settings
|
||||
|
||||
|
|
@ -153,10 +147,6 @@ The Solaar GUI takes these settings and constructs an interface for displaying a
|
|||
|
||||
This setup allows for very quick implementation of simple settings but it bypasses the data stored in a device object.
|
||||
|
||||
TODO: Refactor settings so that they always use data stored in device objects. Set up code to create a device data as easily as simple settings are creates. Set up code to use this to create a setting object for the Solaar GUI. Use callbacks to control GUI redisplay whenever the device data changes.
|
||||
|
||||
|
||||
|
||||
|
||||
### Solaar Rules
|
||||
|
||||
|
|
@ -173,8 +163,6 @@ The module `common.py` provides utility functions, structures, and classes.
|
|||
`FirmwareInfo` provides information about device firmware.
|
||||
`BATTERY_APPROX` provides named integers used for approximate battery levels of devices.
|
||||
|
||||
TODO: Move a couple of things from hidpp20 to here.
|
||||
|
||||
`i18n.py` provides a few strings that need translations and might not otherwise be visible to translation software.
|
||||
|
||||
`special_keys.py` provides named integers for various collections of key codes and colors.
|
||||
|
|
@ -192,8 +180,6 @@ Device and receiver discovery is performed when Solaar starts. While the Solaar
|
|||
|
||||
This code is also responsible for actual writing data to devices and receivers and reading data from them.
|
||||
|
||||
TOD: Is this actually the case?
|
||||
|
||||
|
||||
## Solaar
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,26 @@
|
|||
# Developer Documentation
|
||||
|
||||
::: lib.hidapi
|
||||
handler: python
|
||||
options:
|
||||
recursive: true
|
||||
|
||||
::: lib.hid_parser
|
||||
handler: python
|
||||
options:
|
||||
recursive: true
|
||||
|
||||
::: lib.keysyms
|
||||
handler: python
|
||||
options:
|
||||
recursive: true
|
||||
|
||||
::: lib.logitech_receiver
|
||||
handler: python
|
||||
options:
|
||||
recursive: true
|
||||
|
||||
::: lib.solaar
|
||||
handler: python
|
||||
options:
|
||||
recursive: true
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 96 B |
Binary file not shown.
|
Before Width: | Height: | Size: 432 B |
Binary file not shown.
|
Before Width: | Height: | Size: 230 B |
Binary file not shown.
|
Before Width: | Height: | Size: 14 KiB |
|
|
@ -0,0 +1,33 @@
|
|||
site_name: Solaar Documentation
|
||||
site_description: Linux Device Manager for Logitech Unifying Receivers and Devices.
|
||||
site_author: pwr-Solaar
|
||||
repo_url: https://github.com/pwr-Solaar/Solaar
|
||||
repo_name: Solaar
|
||||
logo: img/favicon.png
|
||||
theme:
|
||||
name: readthedocs
|
||||
docs_dir: docs
|
||||
nav:
|
||||
- Solaar: index.md
|
||||
- Capabilities: capabilities.md
|
||||
- Debian: debian.md
|
||||
- Devices: devices.md
|
||||
- Features: features.md
|
||||
- Translation: i18n.md
|
||||
- Implementation: implementation.md
|
||||
- Installation: installation.md
|
||||
- Rules: rules.md
|
||||
- Usage: usage.md
|
||||
|
||||
- Developer Documentation: reference/developer_documentation.md
|
||||
|
||||
plugins:
|
||||
- search
|
||||
- mkdocstrings:
|
||||
handlers:
|
||||
python:
|
||||
setup_commands:
|
||||
- python -m pip install .
|
||||
- mermaid2
|
||||
markdown_extensions:
|
||||
- pymdownx.superfences
|
||||
Loading…
Reference in New Issue