diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 82f6adc..3bcd636 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -15,17 +15,5 @@ build: # rust: "1.64" # golang: "1.19" -# Build documentation in the "docs/" directory with Sphinx -sphinx: - configuration: docs/conf.py -# Optionally build your docs in additional formats such as PDF and ePub -# formats: -# - pdf -# - epub - -# Optional but recommended, declare the Python requirements required -# to build your documentation -# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html -# python: -# install: -# - requirements: docs/requirements.txt +mkdocs: + configuration: mkdocs.yml diff --git a/docs/dictionaries.md b/docs/dictionaries.md new file mode 100644 index 0000000..ed7582a --- /dev/null +++ b/docs/dictionaries.md @@ -0,0 +1,25 @@ +# Dictionary Settings + +All Kalba dictionaries can be set as a backup dictionary. +In this case, they will only be loaded when the specified dictionary does not return a definition. +All the dictionaries can also be set to not be fetched by default. +This speeds up load times, and also allows them to be "popped out" into a new resizable pane. + +## General Dictionaries + +### File + +Kalba accepts stardict or dictionaries delimited by a specific character. + +### Url + +Kalba can embed websites with the embed option or fetch an API. (TODO: allow using a selector) + +### Wiktionary + +Kalba can automatically fetch any Wiktionary language pair. + +## Specific dictionaries + +Kalba also includes dictionaries for Bendrinės lietuvių kalbos žodynas and Dabartinės lietuvių kalbos žodynas. +Other dictionaries will be added soon. diff --git a/docs/grammar.md b/docs/grammar.md new file mode 100644 index 0000000..8eb35c5 --- /dev/null +++ b/docs/grammar.md @@ -0,0 +1,11 @@ +# Grammar + +The grammar settings for a particular language can be accessed in the Settings tab under the language specific settings menu. + +One of the most important of these settings is the Stanza model. +If you have stanza enabled (see [Stanza](stanza.md) for the benefits and downsides as well as how to do so), you can choose a specific model that can automatically parse the language for you. +[This page](https://stanfordnlp.github.io/stanza/performance.html) includes every model across all languages and statistics about how accurate they are. + +Another important setting is the frequency list. This can be used to automatically assign [Word Knowledge](word_knowledge.md) and will have other uses in the future. + +Finally, the Grammar Parser section allows writing custom [spyglys](https://github.com/BrewingWeasel/spyglys) code to automatically transform lemmas. See [Writing a custom spyglys parser] or the existing templates for more. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..48a1cd7 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,6 @@ +# Kalba + +Kalba is a tool for language learning based on the idea of sentence mining. +Note that this wiki is a work in progress and is currently very incomplete. + +This wiki includes information for both using and configuring Kalba. diff --git a/docs/input.md b/docs/input.md new file mode 100644 index 0000000..97c5442 --- /dev/null +++ b/docs/input.md @@ -0,0 +1,11 @@ +# Reader settings + +Aside from reading from files and the clipboard, Kalba can also parse web pages. +If Kalba has been configured to parse the page, it can maintain the headings and images as a style. +Otherwise, it will fall back to a default parser which will contain all of the text but lose the formatting. + +## Configuring a parser + +(TODO: allow pulling new parsers down) +Users can add their own individual parsers to the bottom of the table. +Each parser contains a list of the URL patterns that they can parse, as well as CSS selectors for various elements of the page, such as headings and images. diff --git a/docs/profiles.md b/docs/profiles.md new file mode 100644 index 0000000..acc4eb1 --- /dev/null +++ b/docs/profiles.md @@ -0,0 +1,14 @@ +# Profiles + +In general, users will have one profile per language they use Kalba for. +Each profile independently keeps track of Word Knowledge, dictionaries, grammar and other language specific settings. + +## Templates + +When creating a new profile, users will be presented with profile templates. +These templates generally correspond to a specific language and include useful defaults such as dictionaries, frequency lists and spyglys grammars. +If none of the templates match your language, you can always use the "custom" template, which provides a clean slate for your new profile. + +## Changing profiles + +The quick settings section at the top right of every page provides an option for switching profiles. (TODO: also add a command) diff --git a/docs/reader.md b/docs/reader.md new file mode 100644 index 0000000..d76daa9 --- /dev/null +++ b/docs/reader.md @@ -0,0 +1,39 @@ +# Reader + +The reader is the most important page in Kalba and can be accessed with the book icon in the navigation menu to the left. + +The reader view can be used in several different modes: + +- File + Kalba can use the contents of a file as the basis for the reader, though this currently only supports raw text files. +- Manual + With this input method, users can input their own text. +- Url + Kalba can automatically fetch (and sometimes parse) the contents of a Url to use as input. + See [input settings](input.md) for more. +- Clipboard + This reader automatically updates its contents every time the clipboard is changed. + This can be very useful in conjunction with other tools such as ASB player. + +The reader view itself is composed of three main parts: + +- The text + This section includes the main text of the input, with every word color-coded based on [Word Knowledge](word_knowledge.md). + Clicking on any word results in it popping up in the selected word panel. +- Selected word panel + The top of this panel includes the detected lemma (root word) of the selected word, which can be modified. + Pressing the check mark next to the lemma will always apply the same changes that you have made whenever this lemma is encountered. + + Underneath the lemma there may be one or more small gray buttons. These can be used to change the detected lemma into another form. + For example, although `singer` is the lemma of `singers`, the definition of `sing` may be more useful to remember. + This detection can be changed in the [grammar settings](grammar.md). + + The next section is the rating buttons, which allow users to manually update their Word Knowledge. + Underneath the rating buttons are definitions, some of which can be popped out into panels of their own (see [Dictionary settings](dictionaries.md)). + + The bottom of this panel includes information about the grammar of the word in this context. + Additionally, it includes an export button (which can be activated with ctrl-e) for adding cards to Anki. + Shift clicking this button (or pressing ctrl-shift-e) will add the card to Anki without the configuration menu. + +- The status bar + This bar includes some stats about the current input, the undo and redo buttons, and will eventually include more tools. diff --git a/docs/word_knowledge.md b/docs/word_knowledge.md new file mode 100644 index 0000000..d8080e0 --- /dev/null +++ b/docs/word_knowledge.md @@ -0,0 +1,33 @@ +# Word Knowledge + +## Overview + +In Kalba, the concept of `Word Knowledge` is used to keep track of how well users know words. + +One especially useful feature of Kalba is the ability to automatically import Word Knowledge from Anki. +By checking the interval rate of the notes, Kalba can automatically keep your Word Knowledge up-to-date + +## Types of word knowledge + +Words can be one of six states + +- Unknown: + This is the state that all words begin as. +- Learning: + This state is automatically assigned to words that have been added to Anki but have yet to be reviewed or have an interval of one. +- Recognized: + This state is automatically assigned to words that have an interval of less than 9 +- Familiar: + This state is automatically assigned to words that have an interval of less than 23 +- Known: + This state is automatically assigned to words that have an interval of over 23. +- Ignored: + If stanza is enabled, any words that are detected as proper nouns will automatically be set to ignored. (TODO: you should be able to disable this feature) + This state is generally meant for names or other "words" the user doesn't want to learn. + +TODO: You should be able to customize the intervals + +## Managing word knowledge + +Although most word knowledge can be automatically imported from Anki, the user can always modify the knowledge of the word in the selected word view. +For information on configuring Word Knowledge, see [profile specific word knowledge settings](word_knowledge_settings.md). diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..710be1e --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,12 @@ +site_name: Kalba +nav: + - Home: "index.md" + - "Word Knowledge": "word_knowledge.md" + - Usage: + - Reader: "reader.md" + - Configuration: + - Profiles: "profiles.md" + - Grammar: "grammar.md" + - Dictionaries: "dictionaries.md" + - Input: "input.md" +theme: readthedocs