Documentation updates

jonathanfox5 · Nov 25, 2024 · 9b7cb65 · 9b7cb65
1 parent 939a94c
commit 9b7cb65
Show file tree

Hide file tree

Showing 13 changed files with 33 additions and 32 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -11,4 +11,4 @@ poetry install
 poetry shell
 
 # Run the tool
-gogadget
+gogadget
diff --git 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
+iscc install/gogadget_windows.iss