Skip to content

Commit

Permalink
Update landing pages, plus doc fixes (#2443)
Browse files Browse the repository at this point in the history
This PR fixes some dodgy headings in the library listings, but mainly it's intended to try and highlight some of the more distinctive features of the framework in the main README file (both repository and readthedocs).
  • Loading branch information
mikee47 authored Dec 10, 2021
1 parent 874fdf9 commit 9c6722a
Show file tree
Hide file tree
Showing 9 changed files with 161 additions and 48 deletions.
7 changes: 5 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,10 @@ Please note Version 4 documentation is at [sming.readthedocs.io](https://sming.r
* Fast and user friendly development.
* Simple yet powerful hardware API wrappers.
* Compatible with standard [Arduino Libraries](https://sming.readthedocs.io/en/latest/libraries.html) - use any popular hardware in few lines of code.
* Built-in file system: [spiffs](https://github.com/pellepl/spiffs).
* Installable file systems:
[SPIFFS](https://sming.readthedocs.io/en/latest/_inc/Sming/Libraries/Spiffs/index.html),
[LittleFS](https://sming.readthedocs.io/en/latest/_inc/Sming/Libraries/LittleFS/index.html) and
[FWFS](https://sming.readthedocs.io/en/latest/_inc/Sming/Components/IFS/index.html)
* Built-in powerful wireless modules.
* Powerful asynchronous (async) network stack.
* Async TCP and UDP stack based on [LWIP](http://savannah.nongnu.org/projects/lwip/).
Expand All @@ -77,7 +80,7 @@ Please note Version 4 documentation is at [sming.readthedocs.io](https://sming.r
* Based on Espressif NONOS SDK. Officially suppored NON SDK version is >= 3.0.1.
* Support for a [thin No-Wifi-SDK](https://sming.readthedocs.io/en/latest/_inc/Sming/Arch/Esp8266/Components/esp_no_wifi/index.html). Helpful when a project does not require WiFi (or networking) and reduces code size and memory usage signficantly.
* Linux/Windows features
* Sming has a [host emulator](https://sming.readthedocs.io/en/latest/arch/host/index.html) that allows libraries and sample applications to be compiled on a Linux/Windows host system and be tested before uploading them to an actual microcontroller.
* Sming has a [host emulator](https://sming.readthedocs.io/en/latest/arch/host/index.html) that allows libraries and sample applications to be developed and tested on a Linux/Windows host system before uploading them to an actual microcontroller.

## Compatibility

Expand Down
2 changes: 1 addition & 1 deletion Sming/Arch/Esp32/Components/esp32/README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ Background
An empty ESP IDF project is built which generates a set of libraries and headers
which the framework can then be built against.

The project is located in ``project/{SMING_SOC}`.
The project is located in ``project/{SMING_SOC}``.

The code for this project is copied from ``sdk/project``.

Expand Down
18 changes: 18 additions & 0 deletions Sming/Libraries/.patches/Adafruit_BME280_Library/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Adafruit BME280 Library

[![Build Status](https://github.com/adafruit/Adafruit_BME280_Library/workflows/Arduino%20Library%20CI/badge.svg)](https://github.com/adafruit/Adafruit_BME280_Library/actions)[![Documentation](https://github.com/adafruit/ci-arduino/blob/master/assets/doxygen_badge.svg)](http://adafruit.github.io/Adafruit_BME280_Library/html/index.html)

<a href="http://www.adafruit.com/products/2652"><img src="https://raw.githubusercontent.com/adafruit/Adafruit_BME280_Library/master/assets/board.jpg" width="500"/></a>

This is a library for the Adafruit BME280 Humidity, Barometric Pressure + Temp sensor

Designed specifically to work with the [Adafruit BME280 Breakout](http://www.adafruit.com/products/2652).

Adafruit invests time and resources providing this open source code, please support Adafruit and open-source hardware by purchasing products from Adafruit!

## About this Driver
Written by Ladyada for Adafruit Industries.

BSD license, check license.txt for more information

All text above must be included in any redistribution
12 changes: 12 additions & 0 deletions Sming/Libraries/.patches/Adafruit_BusIO.patch
Original file line number Diff line number Diff line change
Expand Up @@ -76,3 +76,15 @@ index 921030a..170dce3 100644

#endif // Adafruit_SPIDevice_h
-#endif // has SPI defined
diff --git a/README.md b/README.md
index 3fc8a1f..fba70bd 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,6 @@
-# Adafruit Bus IO Library [![Build Status](https://github.com/adafruit/Adafruit_BusIO/workflows/Arduino%20Library%20CI/badge.svg)](https://github.com/adafruit/Adafruit_BusIO/actions)
+# Adafruit Bus IO Library

+[![Build Status](https://github.com/adafruit/Adafruit_BusIO/workflows/Arduino%20Library%20CI/badge.svg)](https://github.com/adafruit/Adafruit_BusIO/actions)

This is a helper libary to abstract away I2C & SPI transactions and registers

2 changes: 0 additions & 2 deletions docs/index.mk
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@
# $2 -> Path
# $3 -> Source path relative to working root directory (SMINGDIR)
define GenIndex
:custom_pagename: $(patsubst ../%,%,$(CMP_$2_README))

$(if $(filter %.rst,$(CMP_$2_README)),
.. include:: $(call GetIncludePath,$(CMP_$2_README)),
.. mdinclude:: $(call GetMdIncludePath,$(CMP_$2_README))
Expand Down
25 changes: 4 additions & 21 deletions docs/source/_templates/breadcrumbs.html
Original file line number Diff line number Diff line change
Expand Up @@ -10,32 +10,15 @@
{% set suffix = '' %}
{% endif %}

{% if meta is defined and meta.custom_pagename is defined %}
{% set pagename = meta.custom_pagename %}
{% elif '_inc/' in pagename %}
{% set pagename = pagename|replace('_inc/','') + suffix %}
{% if pagename.startswith('_inc/') %}
{% set github_url = page_urls.get(pagename + suffix) %}
{% else %}
{% set pagename = conf_py_path + pagename + suffix %}
{% endif %}

{% if meta is defined and meta is not none %}
{% if 'github_url' in meta %}
{% set github_url = meta.github_url %}
{% set display_github = True %}
{% endif %}
{% endif %}

{% if github_url is not defined %}
{% set github_url = 'https://' + github_host|default('github.com') + '/' + github_user + '/' + github_repo + '/' + theme_vcs_pageview_mode|default('blob') + '/' + github_version + '/' + pagename %}
{% set github_url = 'https://' + github_host|default('github.com') + '/' + github_user + '/' + github_repo + '/blob/' + github_version + '/' + conf_py_path + pagename + suffix %}
{% endif %}

<li class="wy-breadcrumbs-aside">
{% if github_url is not none %}
<a href="{{ github_url }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
{% elif show_source and source_url_prefix %}
<a href="{{ source_url_prefix }}{{ pagename }}{{ suffix }}">{{ _('View page source') }}</a>
{% elif show_source and has_source and sourcename %}
<a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow"> {{ _('View page source') }}</a>
<a href="{{ github_url }}" class="fa fa-github"> {{ _('View on GitHub') }}</a>
{% endif %}
</li>

Expand Down
4 changes: 4 additions & 0 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
from sphinx.util.nodes import set_role_source_info, split_explicit_title
# So our custom extensions can be found
sys.path.insert(0, os.path.abspath('.'))
from filemap import buildFileMap


# -- Project information -----------------------------------------------------
Expand Down Expand Up @@ -117,6 +118,7 @@
"github_repo": "Sming",
"github_version": "develop",
"conf_py_path": "/docs/source/", # Path in the checkout to the docs root
"page_urls": {},
}

##
Expand All @@ -138,3 +140,5 @@

subprocess.call('make -C ../../Sming submodules SMING_ARCH=Host', shell=True)
subprocess.call('make -C .. setup api API_VERSION="' + version + '"', shell=True)

html_context['page_urls'] = buildFileMap(html_context)
70 changes: 70 additions & 0 deletions docs/source/filemap.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
#
# Build map of output files to source URLs so that edit links are created correctly
#

import os
import sys
import subprocess
import shutil

SMINGDIR = "../.."
GIT = shutil.which('git')


def gitcmd(args, **kwargs):
kwargs['stdout'] = subprocess.PIPE
with subprocess.Popen([GIT] + args, **kwargs) as child:
return child.stdout.read().decode()


def urljoin(elements):
res = ''
for e in elements:
if e == '':
continue
if res != '' and not res.endswith('/'):
res += '/'
res += e
return res


def getRemotePath(srcdir):
return gitcmd(['rev-parse', '--show-prefix'], cwd=srcdir).strip()


def getRemoteUrl(srcdir):
return gitcmd(['config', '--get', 'remote.origin.url'], cwd=srcdir).strip()


def getRemoteCommit(srcdir):
return gitcmd(['describe', '--always', 'HEAD'], cwd=srcdir).strip()


# Get map of directories to submodule URLs
def buildFileMap(ctx):
# index.rst files may be generated from README.md or README.rst
def getSourceFilename(srcdir, filename):
if filename != 'index.rst':
return filename
if os.path.exists(f"{srcdir}/README.md"):
return 'README.md'
if os.path.exists(f"{srcdir}/README.rst"):
return 'README.rst'
return filename

filemap = {}
for dirpath, dirnames, filenames in os.walk('_inc'):
srcpath = dirpath[5:] # skip '_inc/'
srcdir = os.path.join(SMINGDIR, srcpath)
# print(f"srcdir = {srcdir}", file=sys.stderr)
remotePath = getRemotePath(srcdir)
url = os.path.splitext(getRemoteUrl(srcdir))[0]
commit = getRemoteCommit(srcdir)
for f in filenames:
s = urljoin([url, 'blob', commit, remotePath, getSourceFilename(srcdir, f)])
filemap[f"{dirpath}/{f}"] = s

# for k, v in filemap.items():
# print(f"{k}: {v}", file=sys.stderr)

return filemap
69 changes: 47 additions & 22 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,8 @@ Welcome to Sming Framework

**Let's do smart things!!!**

Sming is an asynchronous C/C++ framework with superb performance and multiple network features.
Sming is open source and is tailored towards embedded devices.
It supports multiple architectures as ESP8266 for example.
Sming is an asynchronous embedded C/C++ framework with superb performance and multiple network features.
Sming is open source, modular and supports :doc:`multiple architectures <features>` including ESP8266 and ESP32.

|samples|_

Expand All @@ -19,31 +18,57 @@ Summary
-------
- Superb performance and memory usage (Sming compiles to native firmware!)
- Fast and user friendly development
- Simple yet powerful hardware API wrappers
- Compatible with standard :doc:`libraries` - use any popular hardware in few lines of code
- Multiple file system support: :component:`IFS`, :library:`Spiffs`, :library:`LittleFS`
- Integrated :doc:`host emulator <arch/host/index>` to assist with developing, testing and debugging
libraries and applications on a PC before uploading them to an actual microcontroller.
Try it out online `here <https://www.katacoda.com/slaff/scenarios/sming-host-emulator>`__.
- Built-in powerful wireless modules
- Powerful asynchronous (async) network stack.
- Compatible with standard :doc:`libraries` - use popular hardware in few lines of code
- Simple yet powerful hardware API wrappers

- Standard Arduino-style wrappers for simplicity and flexibility
- :library:`HardwareSPI` library provides advanced asynchronous SPI device master capability
including use of ESP8266 'overlapped' mode for reduced pin usage and dual/quad I/O support.
- :library:`Graphics` implements asynchronous display control model with low memory usage,
transparency (alpha-blending) and flexible scripted resource management.

- Modular C++ installable file system interface

- Supports popular :library:`SPIFFS <Spiffs>` and :library:`LittleFS <LittleFS>` filing systems
- New :component:`FWFS <IFS>` read-only filesystem can be used as base file system,
with read/write filesystems mounted in sub-directories
- Integrated metadata support (file times, security descriptors, user metadata)
- Access to Host (linux / Windows / MacOS) filing system via same API
- Integrated streaming archival system to support backups or file system compaction operations

- Powerful asynchronous (async) :doc:`network stack </_inc/Sming/Components/Network/index>` including:

- Async TCP and UDP stack based on `LWIP <http://savannah.nongnu.org/projects/lwip/>`__.
- With clients supporting: HTTP, MQTT, WebSockets and SMTP.
- And servers for: DNS, FTP, HTTP(+ WebSockets), Telnet.
- With :doc:`SSL support <_inc/Sming/Components/ssl/index>` for all network clients and servers.
Based on `axTLS <http://axtls.sourceforge.net/>`__ and `BearSSL <https://www.bearssl.org/>`__.
- Over-The-Air (OTA) firmware upgrades via HTTP(S) and MQTT(S).

- :library:`UPnP <Universal Plug and Play (UPnP)>`
framework supports both standard and custom devices with full ControlPoint support.

- Generates C++ code from standard UPnP XML schema.
- Companion :library:`SSDP` library independently supports discovery on local network.
- :library:`GoogleCast` library allows control of ChromeCast devices or smart TVs supporting the GoogleCast protocol.
- :library:`HueEmulator` provides simple way to implement devices compatible with Amazon Alexa.

- Async TCP and UDP stack based on `LWIP <http://savannah.nongnu.org/projects/lwip/>`__.
- With clients supporting: HTTP, MQTT, WebSockets and SMTP.
- And servers for: DNS, FTP, HTTP(+ WebSockets), Telnet.
- With :doc:`SSL support <_inc/Sming/Components/ssl/index>` for all network clients and servers.
Based on `axTLS <http://axtls.sourceforge.net/>`__ and `BearSSL <https://www.bearssl.org/>`__.
- Over-The-Air(OTA) firmware upgrades via HTTP(S) and MQTT(S).
- ESP8266 features

- ESP8266 specific features
- Integrated boot loader :component:`rboot` with support for 1MB ROMs, OTA firmware updating and ROM switching.
- :doc:`Crash handlers <information/debugging>` for analyzing/handling system restarts due to fatal errors or WDT resets.
- :component-esp8266:`PWM support <driver>` based on `Stefan Bruens PWM <https://github.com/StefanBruens/ESP8266_new_pwm.git>`__.
- Optional :component-esp8266:`custom heap allocation <heap>` based on `Umm Malloc <https://github.com/rhempel/umm_malloc.git>`__.
- Based on :component-esp8266:`Espressif NONOS SDK Version 3 <esp8266>`.

- Integrated boot loader :component:`rboot` with support for 1MB ROMs, OTA firmware updating and ROM switching.
- :doc:`Crash handlers <information/debugging>` for analyzing/handling system restarts due to fatal errors or WDT resets.
- :component-esp8266:`PWM support <driver>` based on `Stefan Bruens PWM <https://github.com/StefanBruens/ESP8266_new_pwm.git>`__.
- Optional :component-esp8266:`custom heap allocation <heap>` based on `Umm Malloc <https://github.com/rhempel/umm_malloc.git>`__.
- Based on :component-esp8266:`Espressif NONOS SDK <esp8266>`. Tested with versions 1.5, 2.0 and 3.0.
- ESP32 features

- Linux/Windows features
- Based on :component-esp32:`ESP IDF SDK <esp32>`

- Sming has a :doc:`host emulator <arch/host/index>` that allows libraries and sample applications to be compiled on a Linux/Windows host system
and be tested before uploading them to an actual microcontroller.

.. toctree::
:caption: Contents:
Expand Down

0 comments on commit 9c6722a

Please sign in to comment.