SpaceSharp Docs
For contributors

Editing the docs

These pages are plain Markdown, one file per page, in the SpaceSharp repository under docs-src/. docs.spacesharp.app is built from them on every change: edit a file, open a pull request (or push, if you have write access), and the site follows a minute after it lands on main. The GitHub wiki is a single page pointing here.

Two ways to edit

In the browser. Edit on GitHub, at the side of every page, opens its file on GitHub. Change the text, propose the change, and GitHub opens the pull request for you. Good for a sentence or a table row.

Locally. In a clone of the repository, edit the files in docs-src/, then preview the site before you push:

pip install markdown
python tools/docs-site/build.py docs-src out

and open out/index.html. Good for a new page, several pages at once, or anything with pictures. A change to a screen in the app belongs in the same pull request as the page that describes it.

How the pages fit together

File What it is
Home.md The front page
_Sidebar.md The navigation on every page. Add a line here when you add a page.
_Footer.md The line at the bottom of every page; says which version the docs describe
Page-Name.md One page. The file name is the title with hyphens for spaces; Settings-Reference.md shows as "Settings Reference" and is linked as [Settings reference](/settings-reference/).
images/ Screenshots, referenced as images/name.png

Links between pages use the file name without .md: [The filter](/the-filter/). Links to a heading add the heading in lowercase with hyphens: [Changes](/changes/#filters).

Conventions

  • One page answers one question. If a page needs a second "## Overview" halfway down, it is two pages.
  • Describe the app as it is, in the present tense, in the words the app itself uses (Safe to clear, Changes, Color by). Version history belongs in the changelog; a page may say "since 2.5" when it helps.
  • American English, plain words, short sentences. Headings in sentence case.
  • Tables for reference, prose for explanation. The Settings reference and Keyboard shortcuts pages are tables on purpose; the other pages should read as text.
  • No dashes as punctuation; use a comma, a colon or a new sentence.
  • Screenshots come from the app, never from a hand-cropped window. tools/screenshots_docs.ps1 renders every picture these pages use on the pretend PC and writes them straight into docs-src/images (-Out points elsewhere). Pass scene names to redo a few. The scenes themselves are the WikiScenes list in SpaceSharp/MainWindow.Showcase.cs; a new picture is a new case there, a line in the script's table, and the <img> on the page.

When a release ships

  1. Go through the pages that the release touched; the changelog section lists them by name (Palettes, Scanning, Settings, and so on).
  2. Update the version in _Footer.md.
  3. Replace the "New in" list on Home.md with the new release's three or four headline items.
  4. Regenerate the pictures whose screens changed with .\tools\screenshots_docs.ps1 and commit them with the pages. The site updates itself when the commit lands on main.

The pictures

File Scene Shows
screenshot.png, shot-start.png, shot-filter.png, shot-insights.png, shot-changes.png, shot-inspect.png, shot-menu.png, shot-settings.png, shot-about.png, shot-update.png, shot-light.png, shot-duplicates.png the README's scenes the same pictures the README shows
colorby-top.png, colorby-type.png wiki-colorby-top, wiki-colorby-type the Color by modes
shading.png wiki-shading cushion shading at the Deep preset
zoomed.png wiki-zoomed the map zoomed three folders down
filter-rail.png, filtered.png wiki-rail, wiki-filtered the rail layout; a filtered map without the drawer
palette-picker.png, palettes.png, palette-editor.png wiki-palette-picker, wiki-palettes, wiki-palette-editor the picker open; the sheet of all 24 palettes (drawn by the app, not a window capture); the palette editor
shortcuts.png wiki-shortcuts the Shortcuts window
changes-everything.png wiki-changes-everything Changes with Everything shown, sorted by size now, two folders open
inspect-selection.png wiki-inspect-selection Inspect for several selected files
achievements.png, achievement-toast.png wiki-achievements, wiki-achievement-toast the Achievements window; a toast over the map
empty-folders.png, duplicates.png wiki-empty-folders, wiki-duplicates the two windows behind the Small and empty and Duplicates rows
settings-*.png wiki-settings-* one per Settings page
rtl.png wiki-rtl the window mirrored for a right-to-left language

The Settings reference, Keyboard shortcuts, Command line, Palettes and looks and Custom palettes pages mirror code (SettingsWindow.axaml.cs, ShortcutsWindow.cs, CommandLine.cs, Palette.cs). A pull request that changes one of those should change the page too; the PR template asks.