docs progress

This commit is contained in:
vcoppe
2024-07-09 17:49:18 +02:00
parent d46cb4c2e5
commit 7264445926
40 changed files with 470 additions and 68 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.4 MiB

View File

@@ -0,0 +1,11 @@
<script lang="ts">
export let src;
export let alt: string;
</script>
<div class="flex flex-col items-center py-6 w-full">
<div class="rounded-md overflow-clip shadow-lg mx-auto">
<enhanced:img {src} {alt} class="w-full max-w-3xl" />
</div>
<p class="text-center text-sm text-muted-foreground mt-2">{alt}</p>
</div>

View File

@@ -7,7 +7,7 @@
let module = undefined;
let metadata: Record<string, any> = {};
const modules = import.meta.glob('/src/lib/docs/**/*.{md,svx}');
const modules = import.meta.glob('/src/lib/docs/**/*.mdx');
function loadModule(path: string) {
modules[path]().then((mod) => {
@@ -47,14 +47,21 @@
@apply mb-3;
}
:global(.markdown p > a) {
:global(.markdown h3) {
@apply text-lg;
@apply font-semibold;
@apply pt-1.5;
}
:global(.markdown a) {
@apply text-blue-500;
@apply hover:underline;
}
:global(.markdown p > a) {
@apply text-blue-500;
@apply hover:underline;
:global(.markdown kbd) {
@apply p-1;
@apply rounded-md;
@apply border;
}
:global(.markdown ul) {
@@ -62,6 +69,11 @@
@apply pl-4;
}
:global(.markdown li) {
@apply mt-1;
@apply first:mt-0;
}
:global(.markdown hr) {
@apply my-5;
}

View File

@@ -0,0 +1,7 @@
<script lang="ts">
export let type: 'note' | 'warning' = 'note';
</script>
<div class="bg-accent border-l-8 border-blue-500 p-2 text-sm rounded-md">
<slot />
</div>

View File

@@ -0,0 +1,58 @@
export const guides: Record<string, string[]> = {
'getting-started': [],
menu: ['file', 'edit', 'view', 'settings'],
'files-and-stats': [],
toolbar: ['routing', 'poi', 'scissors', 'time', 'merge', 'extract', 'reduce', 'clean'],
'map-controls': [],
'gpx': [],
};
export function getPreviousGuide(currentGuide: string): string | undefined {
let subguides = currentGuide.split('/');
if (subguides.length === 1) {
let keys = Object.keys(guides);
let index = keys.indexOf(currentGuide);
if (index === 0) {
return undefined;
}
let previousGuide = keys.at(index - 1);
if (previousGuide === undefined) {
return undefined;
} else if (guides[previousGuide].length === 0) {
return previousGuide;
} else {
return `${previousGuide}/${guides[previousGuide][guides[previousGuide].length - 1]}`;
}
} else {
let subguideIndex = guides[subguides[0]].indexOf(subguides[1]);
if (subguideIndex > 0) {
return `${subguides[0]}/${guides[subguides[0]][subguideIndex - 1]}`;
} else {
return subguides[0];
}
}
}
export function getNextGuide(currentGuide: string): string | undefined {
let subguides = currentGuide.split('/');
if (subguides.length === 1) {
if (guides[currentGuide].length === 0) {
let keys = Object.keys(guides);
let index = keys.indexOf(currentGuide);
return keys.at(index + 1);
} else {
return `${currentGuide}/${guides[currentGuide][0]}`;
}
} else {
let subguideIndex = guides[subguides[0]].indexOf(subguides[1]);
if (subguideIndex < guides[subguides[0]].length - 1) {
return `${subguides[0]}/${guides[subguides[0]][subguideIndex + 1]}`;
} else {
let keys = Object.keys(guides);
let index = keys.indexOf(subguides[0]);
return keys.at(index + 1);
}
}
}

View File

@@ -120,7 +120,7 @@
</div>
</Label>
<Label class="flex flex-row gap-2 items-center justify-between">
{$_('menu.style.weight')}
{$_('menu.style.width')}
<div class="w-40 p-2">
<Slider
bind:value={weight}

View File

@@ -0,0 +1,57 @@
---
title: Files and statistics
---
<script>
import { TriangleRight, BrickWall, Zap, HeartPulse, Orbit, Thermometer, SquareActivity } from 'lucide-svelte';
import DocsNote from '$lib/components/docs/DocsNote.svelte';
</script>
# { title }
## File list
Once you have [opened](./menu/file) files, they will be shown as tabs in the file list located at the bottom of the map.
You can reorder the files by dragging and dropping the tabs.
When many files are open, you can scroll through the list of tabs to navigate between them.
### File selection
By clicking on a tab, you can switch between the files to inspect their statistics, and apply [edit actions](./menu/edit) and [tools](./toolbar/) to them.
By holding the <kbd>Ctrl/Cmd</kbd> key, you add files to the selection, and by holding <kbd>Shift</kbd>, you can select a range of files.
Most of the [edit actions](./menu/edit) and [tools](./toolbar/) can be applied to multiple files at once.
<DocsNote>
You can also navigate through the files using the arrow keys on your keyboard, and use <kbd>Shift</kbd> to add files to the selection.
</DocsNote>
### Edit actions
By right-clicking on a file tab, you can access the same actions as in the [edit menu](./menu/edit).
### Vertical layout
As mentioned in the [view options section](./menu/view), you can switch between a horizontal and a vertical layout for the file list.
The vertical file list is useful when you have many files open, or files with multiple [tracks, segments or waypoints](../gpx).
Indeed, this layout allows to inspect the content of the files through collapsible sections.
You can apply [edit actions](./menu/edit) and [tools](./toolbar/) to inner file items.
Furthermore, you can drag and drop the inner items to reorder them, or move them in the hierarchy or even to another file.
## Elevation profile and statistics
At the bottom of the interface, you can find the elevation profile and statistics for the current selection.
### Interactive statistics
When hovering over the elevation profile, a tooltip will show statistics at the cursor position.
To get the statistics for a specific section of the elevation profile, you can drag a selection rectangle on the profile.
Click on the profile to reset the selection.
### Additional data
Using the buttons on the right of the elevation profile, you can optionally color the elevation profile by:
- **Slope** <TriangleRight size="16" class="inline-block" style="margin-bottom: 2px" /> information computed from the elevation data
- **Surface** <BrickWall size="16" class="inline-block" style="margin-bottom: 2px" /> data coming from <a href="https://www.openstreetmap.org/" target="_blank">OpenStreetMap</a>'s <a href="https://wiki.openstreetmap.org/wiki/Key:surface" target="_blank">surface</a> tags. This is only available for files created with **gpx.studio**.
If your selection includes it, you can also visualize: **Speed** <Zap size="16" class="inline-block" style="margin-bottom: 2px" />, **Heart rate** <HeartPulse size="16" class="inline-block" style="margin-bottom: 2px" />, **Cadence** <Orbit size="16" class="inline-block" style="margin-bottom: 2px" />, **Temperature** <Thermometer size="16" class="inline-block" style="margin-bottom: 2px" /> and **Power** <SquareActivity size="16" class="inline-block" style="margin-bottom: 2px" /> data on the elevation profile.

View File

@@ -0,0 +1,38 @@
---
title: Getting started
---
<script lang="ts">
import interfaceScreenshot from '$lib/assets/img/docs/getting-started/interface.png?enhanced';
import DocsImage from '$lib/components/docs/DocsImage.svelte';
</script>
# { title }
Welcome to the official guide of **gpx.studio**!
It will walk you through all the components and tools of the interface, and help you become a proficient user of the application.
<DocsImage src={interfaceScreenshot} alt="Screenshot of the gpx.studio interface" />
As you can see on the screenshot above, the interface is divided into four main sections organized around the map.
Before we dive into the details of each section, let's have a quick overview of the interface.
## Menu
At the top of the interface, you will find the [main menu](./menu).
This is where you can access common actions such as opening, closing and exporting files, undoing and redoing actions, and adjusting the settings of the application.
## Files and statistics
At the bottom of the interface, you will find the list of files that are currently open in the application.
You can click on a file to select it, and display its statistics below the list.
As we will see in the [dedicated section](./files-and-stats), you can select multiple files at once, and also switch to a vertical layout of the list for advanced file management.
## Toolbar
On the left side of the interface, you will find the [toolbar](./toolbar), which contains all the tools you can use to edit your files.
## Map controls
Finally, on the right side of the interface, you will find the [map controls](./map-controls).
These allow you to navigate the map, zoom in and out, and switch between different map styles.

View File

@@ -1,11 +0,0 @@
---
title: Getting started
---
# { title }
Welcome message.
- screenshot of the interface
explain main components of the interface and link to the corresponding sections

View File

@@ -0,0 +1,5 @@
---
title: The GPX file format
---
# { title }

View File

@@ -1,7 +0,0 @@
# Translation 🗣
The website is translated by volunteers on a collaborative translation platform.
You can help complete and improve the translations by joining the <a href="https://crowdin.com/project/gpxstudio" target="_blank">Crowdin project</a>.
[Get in touch](#contact) if you would like to start the translation in a new language.
Any help is greatly appreciated!

View File

@@ -0,0 +1,7 @@
# Translation 🗣
The website is translated by volunteers on a collaborative translation platform.
You can contribute to the translation of the interface by adding or improving translations on the <a href="https://crowdin.com/project/gpxstudio" target="_blank">Crowdin project</a>.
<a href="#contact">Get in touch</a> if you want to start the translation in a new language.
Any help is greatly appreciated!

View File

@@ -0,0 +1,19 @@
---
title: Menu
---
<script lang="ts">
import DocsNote from '$lib/components/docs/DocsNote.svelte';
</script>
# { title }
The main menu, located at the top of the interface, provides access to actions, options and settings divided into several categories:
- [File actions](./menu/file)
- [Edit actions](./menu/edit)
- [View options](./menu/view)
- [Settings](./menu/settings)
<DocsNote>
Most of the menu actions can also be performed using keyboard shortcuts that are displayed in the menu.
</DocsNote>

View File

@@ -1,6 +0,0 @@
---
title: Menu
---
# { title }

View File

@@ -0,0 +1,64 @@
---
title: Edit actions
---
<script lang="ts">
import { Undo2, Redo2, Info, PaintBucket, EyeOff, FileStack, ClipboardCopy, Scissors, ClipboardPaste, Trash2 } from 'lucide-svelte';
import DocsNote from '$lib/components/docs/DocsNote.svelte';
</script>
# { title }
Unlike the file actions, the edit actions can potentially modify the content of the currently selected files.
Moreover, when the vertical layout of the files list is enabled (see [Files and statistics](../files-and-stats)), they can also be applied to [tracks, segments and points of interest](../gpx).
Therefore, we will refer to *file items* to designate the elements that can be modified by these actions.
Note that except for the undo and redo actions, the edit actions are also accessible through the context menu (right-click) of the file items.
### <Undo2 size="16" class="inline-block" style="margin-bottom: 2px" /><Redo2 size="16" class="inline-block" style="margin-bottom: 2px" /> Undo and redo
Using these buttons, you can undo or redo the last actions you performed.
This applies to all actions of the interface but not to view options, application settings or map navigation.
### <Info size="16" class="inline-block" style="margin-bottom: 2px" /> Info...
Open the information dialog of the currently selected file item, where you can see and edit its name and description.
### <PaintBucket size="16" class="inline-block" style="margin-bottom: 2px" /> Appearance...
Open the appearance dialog, where you can change the color, opacity and width of the selected file items on the map.
### <EyeOff size="16" class="inline-block" style="margin-bottom: 2px" /> Hide/unhide
Toggle the visibility of the selected file items on the map.
### <FileStack size="16" class="inline-block" style="margin-bottom: 2px" /> Select all
Add all file items in the current hierarchy level to the selection.
### <ClipboardCopy size="16" class="inline-block" style="margin-bottom: 2px" /> Copy
Copy the selected file items to the clipboard.
<DocsNote>
This action is only available when the vertical layout of the files list is enabled.
</DocsNote>
### <Scissors size="16" class="inline-block" style="margin-bottom: 2px" /> Cut
Cut the selected file items to the clipboard.
<DocsNote>
This action is only available when the vertical layout of the files list is enabled.
</DocsNote>
### <ClipboardPaste size="16" class="inline-block" style="margin-bottom: 2px" /> Paste
Paste the file items from the clipboard to the current hierarchy level, if they are compatible with it.
<DocsNote>
This action is only available when the vertical layout of the files list is enabled.
</DocsNote>
### <Trash2 size="16" class="inline-block" style="margin-bottom: 2px" /> Delete
Delete the selected file items.

View File

@@ -1,5 +0,0 @@
---
title: Edit
---
# { title }

View File

@@ -0,0 +1,44 @@
---
title: File actions
---
<script lang="ts">
import { Plus, FolderOpen, Copy, FileX, Download } from 'lucide-svelte';
import DocsNote from '$lib/components/docs/DocsNote.svelte';
</script>
# { title }
The file actions menu contains pretty self-explanatory file operations.
### <Plus size="16" class="inline-block" style="margin-bottom: 2px" /> New
Create a new empty file.
### <FolderOpen size="16" class="inline-block" style="margin-bottom: 2px" /> Open...
Open files from your computer.
<DocsNote>
You can also drag and drop files directly from your file system into the window.
</DocsNote>
### <Copy size="16" class="inline-block" style="margin-bottom: 2px" /> Duplicate
Create a copy of the currently selected files.
### <FileX size="16" class="inline-block" style="margin-bottom: 2px" /> Close
Close the currently selected files.
### <FileX size="16" class="inline-block" style="margin-bottom: 2px" /> Close all
Close all files.
### <Download size="16" class="inline-block" style="margin-bottom: 2px" /> Export...
Open the export dialog to save the currently selected files to your computer.
### <Download size="16" class="inline-block" style="margin-bottom: 2px" /> Export all...
Open the export dialog to save all files to your computer.

View File

@@ -1,5 +0,0 @@
---
title: File
---
# { title }

View File

@@ -0,0 +1,49 @@
---
title: Settings
---
<script lang="ts">
import { Ruler, Zap, Thermometer, Languages, Sun, PersonStanding, Layers3 } from 'lucide-svelte';
import DocsNote from '$lib/components/docs/DocsNote.svelte';
</script>
# { title }
### <Ruler size="16" class="inline-block" style="margin-bottom: 2px" /> Distance units
Change the units used to display distances in the interface.
### <Zap size="16" class="inline-block" style="margin-bottom: 2px" /> Velocity units
Change the units used to display velocities in the interface.
You can choose between distance per hour, or minutes per distance which can be more suitable for running activities.
### <Thermometer size="16" class="inline-block" style="margin-bottom: 2px" /> Temperature units
Change the units used to display temperatures in the interface.
### <Languages size="16" class="inline-block" style="margin-bottom: 2px" /> Language
Change the language used in the interface.
<DocsNote>
You can contribute to the translation of the interface by adding or improving translations on the <a href="https://crowdin.com/project/gpxstudio" target="_blank">Crowdin project</a>.
<a href="#contact">Get in touch</a> if you want to start the translation in a new language.
Any help is greatly appreciated!
</DocsNote>
### <Sun size="16" class="inline-block" style="margin-bottom: 2px" /> Theme
Change the theme used in the interface.
### <PersonStanding size="16" class="inline-block" style="margin-bottom: 2px" /> Street view source
Change the source used for the [street view control](../map-controls).
The default one is <a href="https://www.mapillary.com" target="_blank">Mapillary</a>, but you can also use <a href="https://www.google.com/streetview/" target="_blank">Google Street View</a>.
Learn more about how to use the street view control in the [map controls section](../map-controls).
### <Layers3 size="16" class="inline-block" style="margin-bottom: 2px" /> Map layers...
This opens a dialog where you can enable or disable map layers, add custom ones, change the opacity of overlays, and more.
More information about map layers can be found in the [map controls section](../map-controls).

View File

@@ -1,5 +0,0 @@
---
title: Settings
---
# { title }

View File

@@ -0,0 +1,41 @@
---
title: View options
---
<script lang="ts">
import { MountainSnow, GalleryVertical, Map, Layers2, Coins, Milestone, Box } from 'lucide-svelte';
</script>
# { title }
This menu provides options to rearrange the interface and the map view.
### <MountainSnow size="16" class="inline-block" style="margin-bottom: 2px" /> Elevation profile
Hide the elevation profile to make room for the map, or show it to inspect the current selection.
### <GalleryVertical size="16" class="inline-block" style="margin-bottom: 2px" /> Vertical file list
Switch between a vertical and a horizontal layout for the file list.
The [vertical file list](../files-and-stats) is useful when you have many files open, or files with multiple [tracks, segments or waypoints](../gpx).
### <Map size="16" class="inline-block" style="margin-bottom: 2px" /> Switch to previous basemap
Change the basemap to the one previously selected through the [map layer control](../map-controls).
### <Layers2 size="16" class="inline-block" style="margin-bottom: 2px" /> Toggle overlays
Toggle the visibility of the map overlays selected through the [map layer control](../map-controls).
### <Coins size="16" class="inline-block" style="margin-bottom: 2px" /> Distance markers
Toggle the visibility of distance markers on the map.
They are displayed for the current selection, like the [elevation profile](../files-and-stats).
### <Milestone size="16" class="inline-block" style="margin-bottom: 2px" /> Direction arrows
Toggle the visibility of direction arrows on the map.
### <Box size="16" class="inline-block" style="margin-bottom: 2px" /> Toggle 3D
Enter or exit the 3D map view.

View File

@@ -1,5 +0,0 @@
---
title: View
---
# { title }

View File

@@ -7,6 +7,7 @@ import { map } from "./stores";
import { base } from "$app/paths";
import { browser } from "$app/environment";
import { languages } from "$lib/languages";
import { locale } from "svelte-i18n";
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
@@ -101,6 +102,13 @@ export function getURLForLanguage(lang: string | null | undefined, path?: string
languageInPath = 'en';
}
if (lang === null || lang === undefined) {
lang = get(locale);
if (lang === null || lang === undefined) {
lang = 'en';
}
}
if (languageInPath === 'en') {
if (lang === 'en') {
return `${base}${newPath}`;

View File

@@ -43,7 +43,7 @@
"celsius": "Celsius",
"fahrenheit": "Fahrenheit",
"language": "Language",
"mode": "Mode",
"mode": "Theme",
"light": "Light",
"dark": "Dark",
"street_view_source": "Street view source",
@@ -51,7 +51,7 @@
"google": "Google",
"layers": "Map layers...",
"distance_markers": "Distance markers",
"direction_markers": "Direction markers",
"direction_markers": "Direction arrows",
"help": "Help",
"donate": "Donate",
"ctrl": "Ctrl",
@@ -67,7 +67,7 @@
"button": "Appearance...",
"color": "Color",
"opacity": "Opacity",
"weight": "Weight"
"width": "Width"
},
"hide": "Hide",
"unhide": "Unhide"

View File

@@ -211,7 +211,7 @@
</div>
<div class="px-12 flex flex-col items-center">
<div class="max-w-5xl flex flex-col items-center gap-6">
<DocsLoader path="home/funding.md" />
<DocsLoader path="home/funding.mdx" />
<Button
href="https://ko-fi.com/gpxstudio"
target="_blank"
@@ -224,7 +224,7 @@
</div>
<div class="px-12 flex flex-col items-center">
<div class="max-w-5xl">
<DocsLoader path="home/translation.md" />
<DocsLoader path="home/translation.mdx" />
</div>
</div>
<div class="px-12 md:px-24 flex flex-col items-center">
@@ -239,7 +239,7 @@
<Logo company="mapbox" class="w-60" />
</a>
</div>
<DocsLoader path="home/mapbox.md" />
<DocsLoader path="home/mapbox.mdx" />
</div>
</div>
</div>

View File

@@ -4,13 +4,7 @@
import { locale } from 'svelte-i18n';
import DocsLoader from '$lib/components/docs/DocsLoader.svelte';
import { page } from '$app/stores';
let guides: Record<string, string[]> = {
'getting-started': [],
menu: ['file', 'edit', 'view', 'settings'],
toolbar: ['routing', 'poi', 'scissors', 'time', 'merge', 'extract', 'reduce', 'clean'],
'map-controls': []
};
import { guides } from '$lib/components/docs/docs';
</script>
<div class="p-12 flex flex-row gap-24">
@@ -24,7 +18,7 @@
? 'font-semibold text-foreground'
: ''}"
>
<DocsLoader path={`${guide}.svx`} titleOnly={true} />
<DocsLoader path={`${guide}.mdx`} titleOnly={true} />
</Button>
{#each guides[guide] as subGuide}
<Button
@@ -36,10 +30,12 @@
? 'font-semibold text-foreground'
: ''}"
>
<DocsLoader path={`${guide}/${subGuide}.svx`} titleOnly={true} />
<DocsLoader path={`${guide}/${subGuide}.mdx`} titleOnly={true} />
</Button>
{/each}
{/each}
</div>
<slot />
<div class="grow">
<slot />
</div>
</div>

View File

@@ -1,6 +1,36 @@
<script lang="ts">
import { page } from '$app/stores';
import { getNextGuide, getPreviousGuide } from '$lib/components/docs/docs';
import DocsLoader from '$lib/components/docs/DocsLoader.svelte';
import { Button } from '$lib/components/ui/button';
import { getURLForLanguage } from '$lib/utils';
import { ChevronLeft, ChevronRight } from 'lucide-svelte';
$: previousGuide = getPreviousGuide($page.params.guide);
$: nextGuide = getNextGuide($page.params.guide);
</script>
<DocsLoader path="{$page.params.guide}.svx" />
<DocsLoader path="{$page.params.guide}.mdx" />
<div class="flex flex-row pt-6">
{#if previousGuide}
<Button
variant="outline"
class="mr-auto"
href={getURLForLanguage(undefined, `/help/${previousGuide}`)}
>
<ChevronLeft size="14" class="mr-1 mt-0.5" />
<DocsLoader path="{previousGuide}.mdx" titleOnly={true} />
</Button>
{/if}
{#if nextGuide}
<Button
variant="outline"
class="ml-auto"
href={getURLForLanguage(undefined, `/help/${nextGuide}`)}
>
<DocsLoader path="{nextGuide}.mdx" titleOnly={true} />
<ChevronRight size="14" class="ml-1 mt-0.5" />
</Button>
{/if}
</div>

View File

@@ -4,7 +4,7 @@ import { mdsvex } from 'mdsvex';
/** @type {import('mdsvex').MdsvexOptions} */
const mdsvexOptions = {
extensions: ['.svx', '.md']
extensions: ['.mdx']
};
/** @type {import('@sveltejs/kit').Config} */