From 9b7cb6524e06dc10c09cc8dfdd44f70feabcfe36 Mon Sep 17 00:00:00 2001 From: Jonathan Fox Date: Mon, 25 Nov 2024 20:36:45 +0000 Subject: [PATCH] Documentation updates --- README.md | 18 +++++++++++------- docs/mkdocs.yml | 1 + docs/pages/getting_started/example_commands.md | 4 ++-- docs/pages/getting_started/example_use_case.md | 14 +++++++------- .../pages/getting_started/getting_resources.md | 2 +- docs/pages/getting_started/installation.md | 2 +- .../getting_started/supported_languages.md | 2 -- docs/pages/getting_started/using_the_tool.md | 6 +++--- docs/pages/index.md | 8 ++++---- docs/pages/misc/other_projects.md | 2 +- docs/pages/reference/default_settings.md | 2 -- install/run_from_source_example.sh | 2 +- install/windows_build.sh | 2 +- 13 files changed, 33 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 445852a..92b4fb1 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ - It tries to solve the problem that many of the most powerful tools available are hard to install, difficult to use or require lots of effort to configure for optimal results. - It is capable of downloading audio and video files, automatically transcribing subtitles from videos and podcasts, and automatically producing filtered Anki decks with sentence audio / translations / screenshots / definitions. -## Quick Start +## Quick start Full documentation is available in the [manual](https://jonathanfox5.github.io/gogadget/). If you want to dive straight in, you may find the following useful: @@ -18,11 +18,11 @@ Full documentation is available in the [manual](https://jonathanfox5.github.io/g - **[Detailed command reference](https://jonathanfox5.github.io/gogadget/reference/command_reference/)**: Every command listed with all possible parameters and examples. Warning - could be overwhelming! - **[Video tutorial](https://jonathanfox5.github.io/gogadget/getting_started/video_tutorial/)**: A video tutorial covering the installation of the tool and an overview of its functions. -## Video Tutorial +## Video tutorial Coming in a few days... -## Key Features +## Key features - Simple, well documented interface that is consistent across each of its tools. - Download video, audio and subtitle files. @@ -34,12 +34,12 @@ Coming in a few days... - Include automatic translations of sentences and definitions of words. - Can be built for an individual episode or a whole season. - Create word frequency analyses for priming purposes. -- One click installer for Windows and simple installation steps for macOS and Linux. +- [One click installer](https://github.com/jonathanfox5/gogadget/releases/) for Windows and [simple installation steps](https://jonathanfox5.github.io/gogadget/getting_started/installation/) for macOS and Linux. - Ability to save defaults so that commands can be kept as short and memorable as possible. -- It supports 19 languages fully with partial support for many more. +- It supports 19 [languages](https://jonathanfox5.github.io/gogadget/getting_started/supported_languages/) fully with partial support for many more. - Once you have installed the resources for your language, all modules apart from `gogadget download` are fully offline. This makes it useful for travelling or processing personal conversations as there is no server involved. -## Example Commands +## Example commands You may prefer to watch the [Youtube Tutorial](https://jonathanfox5.github.io/gogadget/getting_started/video_tutorial/) for demonstrations of the features, including configuration for more advanced users. @@ -63,7 +63,7 @@ gogadget transcribe --input "your folder or filename" --language en Note: If you have followed the steps in [the installation instructions](https://jonathanfox5.github.io/gogadget/getting_started/installation/) to enable GPU transcription, add `--gpu` to the end of the command to significantly speed up the transcription. -### Create Anki Deck +### Create Anki deck Generate Anki cards from a full season of an Italian (`it`) program. Include images / audio on the cards, translate the sentences to the default language (English) and exclude the 1000 most common Italian words: @@ -221,6 +221,10 @@ Alternatively, you can change the value of `whisper_use_gpu` in the settings fil gogadget set-defaults --custom ``` +## More information + +Full documentation is available in the [manual](https://jonathanfox5.github.io/gogadget/). + ## Acknowledgements [gogadget](https://github.com/jonathanfox5/gogadget) © 2024 Jonathan Fox. It is licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/?ref=chooser-v1). All materials in this repository are covered by CC BY-NC-SA 4.0, unless specifically noted below: diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index a2f0eec..5e2fea1 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -77,6 +77,7 @@ markdown_extensions: anchor_linenums: true line_spans: __span pygments_lang_class: true + use_pygments: true - pymdownx.inlinehilite - pymdownx.snippets - pymdownx.superfences diff --git a/docs/pages/getting_started/example_commands.md b/docs/pages/getting_started/example_commands.md index 7b9681a..6b761b9 100644 --- a/docs/pages/getting_started/example_commands.md +++ b/docs/pages/getting_started/example_commands.md @@ -24,7 +24,7 @@ gogadget transcribe --input "your folder or filename" --language en If you have followed the steps in [the installation instructions](../getting_started/installation.md) to enable GPU transcription, add `--gpu` to the end of the command to significantly speed up the transcription. -## Create Anki Deck +## Create Anki deck Generate Anki cards from a full season of an Italian (`it`) program. Include images / audio on the cards, translate the sentences to the default language (English) and exclude the 1000 most common Italian words: @@ -42,4 +42,4 @@ See [this section](../getting_started/getting_resources.md) for details on how t gogadget anki-deck --input "folder name" ``` - An example for setting defaults can be found [here](example_use_case.md). + An example workflow where defaults are set can be found [here](../getting_started/example_use_case.md). diff --git a/docs/pages/getting_started/example_use_case.md b/docs/pages/getting_started/example_use_case.md index 3a1d540..54bca75 100644 --- a/docs/pages/getting_started/example_use_case.md +++ b/docs/pages/getting_started/example_use_case.md @@ -1,12 +1,8 @@ -!!! note "A note on commands" - - This example uses the "short" version of the commands. Using the "standard" commands (that are referenced in some other parts of the documentation) is equally valid. More info [here](../getting_started/using_the_tool.md#short-names) - -## Preparing Priming Materials +## Preparing priming materials The following example is my personal use case for producing priming materials prior to immersing in them. My target language is Italian (`it`) and my native language is English(`en`). I have downloaded a json dictionary, word audio and an exclude list as described in [Getting dictionary, word audio and exclude lists](../getting_started/getting_resources.md). -## Setting Defaults +## Setting defaults As a "one off" task, I set up my default settings by running `gogadget set-defaults --custom`. I changed the following settings from the defaults. [the defaults are set for the widest compatibility, not for a specific workflow] @@ -61,7 +57,11 @@ whisper_use_gpu = "True" Now that these parameters are set, they no longer need to be specified in the commands. -## Running Commands +## Running commands + +!!! note "A note on commands" + + This example uses the "short" version of the commands. Using the "standard" commands (that are referenced in some other parts of the documentation) is equally valid. More info [here](../getting_started/using_the_tool.md#short-names). For this example, let's assume that I'm downloading a playlist of videos for a specific series that I want to learn the key vocabulary for. The URL of this hypothetical playlist is `https://www.videosite.com/playlist_name` and I'm storing everything in a folder called `immersion`. diff --git a/docs/pages/getting_started/getting_resources.md b/docs/pages/getting_started/getting_resources.md index 8e83567..c378b46 100644 --- a/docs/pages/getting_started/getting_resources.md +++ b/docs/pages/getting_started/getting_resources.md @@ -9,4 +9,4 @@ find . -type f -name "*.ogg" -exec sh -c 'ffmpeg -i "$1" "${1%.*}.mp3" && rm "$1"' _ {} \; ``` -- `--excluded-words` is a spreadsheet with words that you don't want included in your deck. This is useful to make sure that you aren't wasting time reviewing words that you already know. [Wiktionary](https://en.wiktionary.org/wiki/Wiktionary:Frequency_lists) is a good source for frequency lists but you could also export your known words from Anki to get a more personalised experience. The only requirement is that the words that you want to filter out should be in column `A` of the spreadsheet though you can use multiple sub-sheets in the file if you wish to organise them. I've uploaded example exclude lists [here](https://github.com/jonathanfox5/gogadget/tree/main/examples/exclude_lists/) +- `--excluded-words` is a spreadsheet with words that you don't want included in your deck. This is useful to make sure that you aren't wasting time reviewing words that you already know. [Wiktionary](https://en.wiktionary.org/wiki/Wiktionary:Frequency_lists) is a good source for frequency lists but you could also export your known words from Anki to get a more personalised experience. The only requirement is that the words that you want to filter out should be in column `A` of the spreadsheet though you can use multiple sub-sheets in the file if you wish to organise them. I've uploaded example exclude lists [here](https://github.com/jonathanfox5/gogadget/tree/main/examples/exclude_lists/). diff --git a/docs/pages/getting_started/installation.md b/docs/pages/getting_started/installation.md index 1dc6db3..8bd4589 100644 --- a/docs/pages/getting_started/installation.md +++ b/docs/pages/getting_started/installation.md @@ -146,7 +146,7 @@ Alternatively, you can change the value of `whisper_use_gpu` in the settings fil gogadget set-defaults --custom ``` -## Custom Installation Notes +## Custom installation notes You should ignore this section if you are using the installation instructions for Windows, macOS or Linux. This is only to help anyone doing their own custom installation. diff --git a/docs/pages/getting_started/supported_languages.md b/docs/pages/getting_started/supported_languages.md index f649251..d456274 100644 --- a/docs/pages/getting_started/supported_languages.md +++ b/docs/pages/getting_started/supported_languages.md @@ -1,5 +1,3 @@ -# Supported Languages - | Language | Code | All Modules | Lemmatiser | Transcriber | Translator | | --------------------- | ---- | ----------- | ---------- | ----------- | ---------- | | Albanian | sq | | | | ✅ | diff --git a/docs/pages/getting_started/using_the_tool.md b/docs/pages/getting_started/using_the_tool.md index 40e1531..7936b42 100644 --- a/docs/pages/getting_started/using_the_tool.md +++ b/docs/pages/getting_started/using_the_tool.md @@ -1,4 +1,4 @@ -## Understanding Commands +## Understanding commands The intended behaviour is that the tool itself will guide the user on how to use it. If you type `gogadget` in a command prompt or terminal window, you will get: @@ -36,9 +36,9 @@ You can also configure defaults so that you don't need to specify as many parame gogadget set-defaults --custom ``` -An example for setting defaults can be found [here](../getting_started/example_use_case.md). +An example workflow where defaults are set can be found [here](../getting_started/example_use_case.md). -## Short Names +## Short names All parameters in all commands have both a "standard" form and a "short" form. You can use whatever works best for you! The following two lines are equivalent. diff --git a/docs/pages/index.md b/docs/pages/index.md index 3bd0f72..60171ea 100644 --- a/docs/pages/index.md +++ b/docs/pages/index.md @@ -14,11 +14,11 @@ - [Detailed command reference](reference/command_reference.md) - [Video tutorial](getting_started/video_tutorial.md) -## Video Tutorial +## Video tutorial Coming in a few days... -## Key Features +## Key features - Simple, well documented interface that is consistent across each of its tools. - Download video, audio and subtitle files. @@ -30,9 +30,9 @@ Coming in a few days... - Include automatic translations of sentences and definitions of words. - Can be built for an individual episode or a whole season. - Create word frequency analyses for priming purposes. -- One click installer for Windows and simple installation steps for macOS and Linux. +- [One click installer](https://github.com/jonathanfox5/gogadget/releases/) for Windows and [simple installation steps](getting_started/installation.md) for macOS and Linux. - Ability to save defaults so that commands can be kept as short and memorable as possible. -- It supports 19 languages fully with partial support for many more. +- It supports 19 [languages](getting_started/supported_languages.md) fully with partial support for many more. - Once you have installed the resources for your language, all modules apart from `gogadget download` are fully offline. This makes it useful for travelling or processing personal conversations as there is no server involved. ## Acknowledgements diff --git a/docs/pages/misc/other_projects.md b/docs/pages/misc/other_projects.md index 7e187e0..3678a8d 100644 --- a/docs/pages/misc/other_projects.md +++ b/docs/pages/misc/other_projects.md @@ -10,7 +10,7 @@ You may also be interested in: - [Translate Horizon: Zero Dawn](https://github.com/jonathanfox5/translate_horizon_zero_dawn): A set of python scripts to build priming and reference materials directly from the game files. - [Plot Vowel Space](https://github.com/jonathanfox5/plot_vowel_space): A set of python scripts to plot your vowel positions and compare them against reference audio. -- [lemon_tizer](https://github.com/jonathanfox5/lemon_tizer): A python library that wraps the `spacy` lemmatiser for use in other language learning tools. +- [LemonTizer](https://github.com/jonathanfox5/lemon_tizer): A python library that wraps the `spacy` lemmatiser for use in other language learning tools. **Other projects** diff --git a/docs/pages/reference/default_settings.md b/docs/pages/reference/default_settings.md index 4c240b7..1d4e0d1 100644 --- a/docs/pages/reference/default_settings.md +++ b/docs/pages/reference/default_settings.md @@ -1,5 +1,3 @@ -# Settings - ## Accessing settings The settings can be accessed with the following command. It will open the settings file in your default GUI text editor on macOS / Linux or in notepad / VSCode on Windows. diff --git a/install/run_from_source_example.sh b/install/run_from_source_example.sh index a5b9eb8..ccfce4c 100644 --- a/install/run_from_source_example.sh +++ b/install/run_from_source_example.sh @@ -11,4 +11,4 @@ poetry install poetry shell # Run the tool -gogadget \ No newline at end of file +gogadget diff --git a/install/windows_build.sh b/install/windows_build.sh index 755fc46..34aaccb 100644 --- a/install/windows_build.sh +++ b/install/windows_build.sh @@ -8,4 +8,4 @@ poetry build cp dist/*.whl install/bin/ # Build windows installer and move to dist folder -iscc install/gogadget_windows.iss \ No newline at end of file +iscc install/gogadget_windows.iss