Skip to content

Commit 4af6734

Browse files
JjaggJjagg
committed
Set up docs
1 parent fb3b114 commit 4af6734

22 files changed

+237
-4
lines changed

‎.github/workflows/build.yml

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,11 @@ name: Build
22

33
on:
44
push:
5+
paths-ignore:
6+
- "docs/**"
57
pull_request:
8+
paths-ignore:
9+
- "docs/**"
610

711
jobs:
812
build:
@@ -17,7 +21,7 @@ jobs:
1721
- packages/boustro
1822
- packages/boustro_starter
1923
- example
20-
include:
24+
include:
2125
- package: packages/boustro_starter
2226
no-tests: true
2327
- package: example
@@ -53,4 +57,3 @@ jobs:
5357
name: ${{ matrix.package }}
5458
fail_ci_if_error: true
5559
if: ${{ !matrix.no-tests }}
56-

‎.github/workflows/docs.yml

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
paths:
6+
- "docs/**"
7+
- "packages/**/CHANGELOG.md"
8+
pull_request:
9+
paths:
10+
- "docs/**"
11+
- "packages/**/CHANGELOG.md"
12+
13+
jobs:
14+
deploy:
15+
runs-on: ubuntu-18.04
16+
steps:
17+
- uses: actions/checkout@v2
18+
19+
- name: Setup mdBook
20+
uses: peaceiris/actions-mdbook@v1
21+
with:
22+
mdbook-version: "0.4.4"
23+
24+
- run: mdbook build
25+
working-directory: docs/
26+
27+
- name: Deploy
28+
uses: peaceiris/actions-gh-pages@v3
29+
with:
30+
github_token: ${{ secrets.GITHUB_TOKEN }}
31+
publish_dir: docs/book

‎.github/workflows/publish_fsp.yml renamed to ‎.github/workflows/publish.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,11 @@ jobs:
1919
matrix:
2020
package:
2121
- packages/flutter_spanned_controller
22-
22+
2323
steps:
2424
- name: Checkout
2525
uses: actions/checkout@v2
26-
26+
2727
- name: Install Flutter
2828
uses: subosito/flutter-action@v1
2929
with:

‎docs/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
book

‎docs/book.toml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
[book]
2+
authors = ["Jesse Gielen"]
3+
language = "en"
4+
multilingual = false
5+
src = "src"
6+
title = "boustro Documentation"
7+
8+
[output.html]
9+
10+
# TODO Should enable linkcheck when we write all drafts
11+
#[output.linkcheck]
12+
## Need this because we include changelog
13+
#traverse-parent-directories = true

‎docs/src/.vscode/ltex.dictionary.en-US.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
boustro

‎docs/src/SUMMARY.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Summary
2+
3+
[Introduction](introduction.md)
4+
5+
- [Quickstart]()
6+
- [Goals](goals.md)
7+
- [Model](model.md)
8+
- [Usage]()
9+
- [Customization](customization.md)
10+
- [Theming boustro]()
11+
- [Toolbar]()
12+
- [Attributes]()
13+
- [Embeds]()
14+
- [Line Modifiers]()
15+
- [boustro\_starter](boustro_starter.md)
16+
- [Serialization]()
17+
- [Changelog](changelog.md)
18+
- [`flutter_spanned_controller`](changelog/fsp.md)
19+
- [`boustro`](changelog/boustro.md)
20+
- [`boustro_starter`](changelog/boustro_starter.md)
21+
22+
---
23+
24+
[API reference](api_reference.md)
25+
[Contribute to boustro](contributing.md)

‎docs/src/api_reference.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# API reference
2+
3+
- [flutter_spanned_controller](https://pub.dev/documentation/flutter_spanned_controller/latest/)
4+
- [boustro](https://pub.dev/documentation/boustro/latest)
5+
- [boustro_starter](https://pub.dev/documentation/boustro_starter/latest)

‎docs/src/boustro_starter.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# `boustro_starter`
2+
3+
Boustro — the rich text editor itself — does not know how to apply text attributes or line
4+
modifiers, or draw any embeds[^components]. Instead, it uses abstractions to make it as
5+
extensible[^extensible] as possible.
6+
7+
A modest set of common components is therefore provided by another library: `boustro_starter`.
8+
It provides range of components that are commonly required in a rich text editor. Here, you'll find
9+
a list of components provided.
10+
11+
## Attributes
12+
13+
- Bold
14+
- Italic
15+
- Underline
16+
- Strikethrough
17+
18+
## Line Modifiers
19+
20+
- Bullet list
21+
- Numbered list
22+
23+
## Embeds
24+
25+
- Image
26+
27+
If you're missing a component that is generally useful, please [open an issue](https://github.com/Jjagg/boustro/issues)
28+
to request it.
29+
30+
[^components]: For an explanation of these concepts, see [Model](model.md).
31+
32+
[^extensible]: See [Customization](customization.md)
33+
for more information about the different ways in which boustro can be
34+
customized.

‎docs/src/changelog.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Changelog
2+
3+
- [flutter_spanned_controller](changelog/fsp.md)
4+
- [boustro](changelog/boustro.md)
5+
- [boustro_starter](changelog/boustro_starter.md)

‎docs/src/changelog/boustro.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# `boustro` Changelog
2+
3+
{{#include ../../../packages/boustro/CHANGELOG.md}}

‎docs/src/changelog/boustro_starter.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# `boustro_starter` Changelog
2+
3+
{{#include ../../../packages/boustro_starter/CHANGELOG.md}}

‎docs/src/changelog/fsp.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# `flutter_spanned_controller` — Changelog
2+
3+
{{#include ../../../packages/flutter_spanned_controller/CHANGELOG.md}}

‎docs/src/contributing.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Contribute to boustro
2+
3+
Boustro is still a very young project that I'm developing for my own
4+
(proprietary) app. I do, however, wish for boustro to become a great
5+
solution for anyone requiring rich text editing capabilities in their
6+
Flutter app.
7+
8+
Bug fixes or small improvements are welcome. For design discussions or
9+
feature requests, please open an [issue](https://github.com/Jjagg/boustro/issues).

‎docs/src/customization.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Customization
2+
3+
Boustro is designed to be extremely customizable.
4+
5+
The `boustro` library itself does not define any `TextAttributes`, `LineModifiers` or
6+
`ParagraphEmbeds`, meaning all of those can be provided by the user. Of course, there's some
7+
common components a rich text editor is supposed to have out of the box.
8+
9+
To that end, a supplementary library called [`boustro_starter`](boustro_starter.md) is developed
10+
alongside boustro. It contains a bunch of components that you can directly use with boustro.
11+
12+
To learn how to:
13+
14+
- Theme `boustro` widgets such as the editor and the toolbar, see [Theming boustro](customization/theming_boustro.md).
15+
- Create and theme attributes, see [Attributes](customization/attributes.md).
16+
- Create and theme line modifiers, see [Embeds](customization/embeds.md).
17+
- Create and theme embeds, see [Embeds](customization/embeds.md).

‎docs/src/customization/attributes.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Attributes

‎docs/src/customization/embeds.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Embeds

‎docs/src/customization/line_modifiers.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Line Modifiers

‎docs/src/customization/theming.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Theming boustro

‎docs/src/goals.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Goals
2+
3+
- Pick and choose formatting and embed options.
4+
- Fully customizable without touching the source code.
5+
- Built in formatting options and embeds for most common use cases.
6+
- Beautiful default dark and light theme.
7+
- Built-in serialization.

‎docs/src/introduction.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Introduction
2+
3+
Welcome! And thank you for checking out boustro 😎
4+
5+
## What is boustro?
6+
7+
Boustro is a rich text editing library for [Flutter](https://flutter.dev).
8+
9+
## About the documentation
10+
11+
This documentation is a work in progress. Greyed out chapters in the navigation bar have not yet
12+
been written.
13+
14+
If you want to try out boustro, for now, the best way to get started is to check out the [example](https://github.com/Jjagg/boustro/tree/main/example).
15+
16+
The documentation is built with [mdBook](https://rust-lang.github.io/mdBook/index.html).

‎docs/src/model.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Model
2+
3+
This chapter describes how rich text content is represented in boustro.
4+
5+
## Document
6+
7+
A document in boustro is a list of lines of formatted text and embeddable content (called embeds).
8+
An immutable document is represented by a [`Document`](https://pub.dev/documentation/boustro/latest/boustro/Document-class.html).
9+
While editing a document, its state is maintained by a [`DocumentController`](https://pub.dev/documentation/boustro/latest/boustro/Document-class.html).
10+
11+
A document holds a collection of [`Paragraphs`](https://pub.dev/documentation/boustro/latest/boustro/Paragraph-class.html).
12+
Paragraphs are either a [`TextLine`](https://pub.dev/documentation/boustro/latest/boustro/TextLine-class.html) —
13+
for rich text content — or an [embed](https://pub.dev/documentation/boustro/latest/boustro/ParagraphEmbed-class.html),
14+
which can be any custom content, for example an image or a code block.
15+
16+
## Text
17+
18+
A text line represents rich text using a [`SpannedString`](https://pub.dev/documentation/flutter_spanned_controller/latest/flutter_spanned_controller/SpannedString-class.html).
19+
Text lines can be modified with [`LineModifiers`](https://pub.dev/documentation/boustro/latest/boustro/LineModifier-class.html).
20+
These modifiers wrap a line of text and can modify how they are displayed or override their style.
21+
For example, `boustro_starter` has modifiers for block quotes or list items (bullet or numbered).
22+
23+
Spanned strings hold text, along with a list of spans that apply formatting or attach gestures to
24+
the text. The mutable version of a `SpannedString` is a [`SpannedTextEditingController`](https://pub.dev/documentation/flutter_spanned_controller/latest/flutter_spanned_controller/SpannedString-class.html) —
25+
a subclass of Flutter's [`TextEditingController`](https://api.flutter.dev/flutter/widgets/TextEditingController-class.html)
26+
that manages formatting of its text.
27+
28+
Both `SpannedString` and `SpannedTextEditingController` maintain a [`SpanList`](https://pub.dev/documentation/flutter_spanned_controller/latest/flutter_spanned_controller/SpanList-class.html).
29+
`SpanList` is an immutable list of [`AttributeSpan`](https://pub.dev/documentation/flutter_spanned_controller/latest/flutter_spanned_controller/AttributeSpan-class.html).
30+
31+
Attribute spans hold three values:
32+
33+
- A range in the source text to which the attribute is applied. The boundaries of the range are
34+
indices into the source text, using [Unicode (Extended) Grapheme Clusters](https://unicode.org/reports/tr29/)
35+
(EGC) as the unit. EGC map to user-perceived characters. EGC indices are used to prevent indices
36+
in the middle of user-perceived characters.
37+
- A [`TextAttribute`](https://pub.dev/documentation/flutter_spanned_controller/latest/flutter_spanned_controller/TextAttribute-class.html).
38+
The attribute can be resolved to a `TextStyle` (to apply formatting) and gestures (for example tap handler that opens a
39+
hyperlink).
40+
- An [`ExpandRule`](https://pub.dev/documentation/flutter_spanned_controller/latest/flutter_spanned_controller/ExpandRule-class.html)
41+
for its start and end indices. These rules determine how the span responds to insertions in the
42+
source text.
43+
44+
## Embeds
45+
46+
Embeds in boustro can be pretty much anything as long as it extends `ParagraphEmbed`.
47+
Users should override the `build` method to create a `Widget` for the embed.
48+
49+
## Component
50+
51+
A component is any implementation of `TextAttribute`, `LineModifier` or `ParagraphEmbed`. This
52+
concept is not used within boustro itself, but it's useful to define it for talking about
53+
[customization](customization.md) in boustro.

0 commit comments

Comments
 (0)