From 23990920809f305d084f295cab7d3e7665dd6728 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20Milants?= Date: Sun, 21 Nov 2021 15:48:56 +0100 Subject: [PATCH] Add configuration files for Sphinx/ReadTheDocs --- .readthedocs.yaml | 17 ++++++++++++ docs/build-flash-and-debug/index.md | 33 +++++++++++++++++++++++ docs/conf.py | 39 +++++++++++++++++++++++++++ docs/credits.md | 1 + docs/developer-documentation/index.md | 6 +++++ docs/going-further.md | 5 ++++ docs/how-to-contribute.md | 1 + docs/index.md | 12 +++++++++ docs/licences.md | 1 + docs/requirements.txt | 1 + docs/setup.cfg | 4 +++ docs/user-documentation/index.md | 20 ++++++++++++++ docs/what-is-infinitime/index.md | 7 +++++ 13 files changed, 147 insertions(+) create mode 100644 .readthedocs.yaml create mode 100644 docs/build-flash-and-debug/index.md create mode 100644 docs/conf.py create mode 100644 docs/credits.md create mode 100644 docs/developer-documentation/index.md create mode 100644 docs/going-further.md create mode 100644 docs/how-to-contribute.md create mode 100644 docs/index.md create mode 100644 docs/licences.md create mode 100644 docs/requirements.txt create mode 100644 docs/setup.cfg create mode 100644 docs/user-documentation/index.md create mode 100644 docs/what-is-infinitime/index.md diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..6b37ab13 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,17 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Optionally build your docs in additional formats such as PDF +formats: all + +python: + install: + - requirements: docs/requirements.txt diff --git a/docs/build-flash-and-debug/index.md b/docs/build-flash-and-debug/index.md new file mode 100644 index 00000000..3f99abfb --- /dev/null +++ b/docs/build-flash-and-debug/index.md @@ -0,0 +1,33 @@ +# Build, flash and debug +## Project branches +## Versioning +## Files included in the release notes +## Build the project +## Build the documentation +### Setup +The documentation is written in Makrdown (.md) files and generated using the Sphinx documentation generator. + +First, we need to install Sphinx and its dependencies: + - `myst-parser` : add support for markdown files + - `sphinx_rtd_theme` : theme from ReadTheDocs +``` +pip install sphinx +pip install myst-parser +pip install sphinx_rtd_theme +``` + +### Build the doc +Run the following command in the folder `docs` +``` +sphinx-build -b html ./ ./generated +``` + +Then display the doc by browsing to `generated/index.html` using your favorite web browser. + +## Flash the firmware using OpenOCD and STLinkV2 +## Build the project with Docker +## Build the project with VSCode +## Bootloader, OTA and DFU +## Stub using NRF52-DK +## Logging with JLink RTT +## Using files from the releases diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..ccb69223 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,39 @@ +# Configuration file for the Sphinx documentation builder. + +# -- Project information + +project = 'InfiniTime' +copyright = '2021, InfiniTime' +author = 'InfiniTime' + +release = '1.7' +version = '1.7.1' + +# -- General configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', + 'myst_parser', +] + +source_suffix = ['.md'] + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), +} +intersphinx_disabled_domains = ['std'] + +templates_path = ['_templates'] + +# -- Options for HTML output + +html_theme = 'sphinx_rtd_theme' + +# -- Options for EPUB output +epub_show_urls = 'footnote' + diff --git a/docs/credits.md b/docs/credits.md new file mode 100644 index 00000000..e94d0070 --- /dev/null +++ b/docs/credits.md @@ -0,0 +1 @@ +# Credits diff --git a/docs/developer-documentation/index.md b/docs/developer-documentation/index.md new file mode 100644 index 00000000..c89f73b8 --- /dev/null +++ b/docs/developer-documentation/index.md @@ -0,0 +1,6 @@ +# Developer documentation +## Rough structure of the code +## How to implement an app +## Generating the fonts and symbols +## Creating a stopwatch in PineTime (article) +## BLE implementation and API diff --git a/docs/going-further.md b/docs/going-further.md new file mode 100644 index 00000000..08e4b330 --- /dev/null +++ b/docs/going-further.md @@ -0,0 +1,5 @@ +# Going further +* The [PineTime wiki](https://wiki.pine64.org/wiki/PineTime) +* InfiniTime resources from other people + * Videos + * Articles \ No newline at end of file diff --git a/docs/how-to-contribute.md b/docs/how-to-contribute.md new file mode 100644 index 00000000..8c2cb1ae --- /dev/null +++ b/docs/how-to-contribute.md @@ -0,0 +1 @@ +# How to contribute \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..1a2d5ad3 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,12 @@ +# InfiniTime + +```{toctree} +what-is-infinitime/index.md +user-documentation/index.md +developer-documentation/index.md +build-flash-and-debug/index.md +how-to-contribute.md +going-further.md +licences.md +credits.md +``` diff --git a/docs/licences.md b/docs/licences.md new file mode 100644 index 00000000..d5d24e65 --- /dev/null +++ b/docs/licences.md @@ -0,0 +1 @@ +# Licences \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..8085d79c --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +myst-parser \ No newline at end of file diff --git a/docs/setup.cfg b/docs/setup.cfg new file mode 100644 index 00000000..d246cda5 --- /dev/null +++ b/docs/setup.cfg @@ -0,0 +1,4 @@ +[options.extras_require] +docs = + sphinx + myst-parser diff --git a/docs/user-documentation/index.md b/docs/user-documentation/index.md new file mode 100644 index 00000000..b69e892a --- /dev/null +++ b/docs/user-documentation/index.md @@ -0,0 +1,20 @@ +# User documentation +## Getting started with InfiniTime +### Unboxing your PineTime +### Boot/Reboot/Switch off InfiniTime +### Setting up date and time +#### Manually +#### Using companion apps +#### Using any Chromium-based web-browser +#### Using NRFConnectr +### Companion apps +### The InfiniTime UI +## Flash And Upgrade +### Firmware, bootloader, recovery firmware +### Upgrading your PineTime +#### Over-The-Air (OTA) +#### Using Gadgetbridge +#### Using Amazfish +#### Using NRFConnect +### Using the SWD interface +## Firmware validation \ No newline at end of file diff --git a/docs/what-is-infinitime/index.md b/docs/what-is-infinitime/index.md new file mode 100644 index 00000000..1314760d --- /dev/null +++ b/docs/what-is-infinitime/index.md @@ -0,0 +1,7 @@ +# What is InfiniTime +## Generalities about PineTime +## InfiniTime goals +## InfiniTime features - high level +## InfiniTime history +### Project history +### Firmwares history and changelog \ No newline at end of file