Skip to content

Commit f17d1d8

Browse files
authored
Add documentation on readthedocs (#36)
Docs are built using Sphinx from the `docs` folder. All the info in the readme is moved there. Action documentation is semi-automatically generated from the yaml definitions. https://kspbuildtools.readthedocs.io/en/docs/ the default url will start working once this is included in a release
1 parent 4b70a91 commit f17d1d8

33 files changed

+746
-499
lines changed

.github/actions/assemble-release/action.yml

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
name: assemble-release
1+
name: Assemble Release
2+
3+
x-env:
4+
RELEASE_STAGING:
5+
description: The artifact files will be copied to this directory before being packaged in the zip file. This becomes the input for `upload-artifact`. If not set, `/tmp/release` is used instead
26

37
inputs:
48
artifacts:
@@ -10,12 +14,12 @@ inputs:
1014
default: "**/*.pdb"
1115

1216
output-file-name:
13-
description: Output artifact name
17+
description: Output artifact name used in the upload-artifact action. a zip file with this name will be created in the github workspace so that it can be immediately consumed by other actions in the workflow without having to download the artifact.
1418
default: ${{ github.event.repository.name || 'release'}}
1519

1620
working-directory:
1721
default: ${{ github.workspace }}
18-
description: the working directory to run in
22+
description: The working directory to run in
1923

2024
outputs:
2125
artifact-id:

.github/actions/build-assetbundles/README.md

Lines changed: 0 additions & 64 deletions
This file was deleted.

.github/actions/build-assetbundles/action.yml

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,14 @@
11
name: Build Assetbundle
2-
description: Build an assetbundle
2+
description: Build a Unity assetbundle
33

44
inputs:
55
unity-version:
6-
description: Full unity version name to build with. e.g. 2019.4.18f1
6+
description: Full unity version name to build with. e.g. `2019.4.18f1`
77
default: '2019.4.18f1'
88

99
project-dir:
1010
description: Location of the Unity project root (The folder that contains `Assets`) *relative to the github workspace*
11+
x-example: '.'
1112

1213
asset-files:
1314
description: Glob of assets to bundle. Mutually exclusive with `project-dir`
@@ -23,6 +24,14 @@ inputs:
2324
description: Method to call to build the assetbundles. Uses a builtin build script with sensible values by default
2425
default: 'KSPBuildTools.AssetBundleBuilder.BuildBundles'
2526

27+
x-env:
28+
UNITY_LICENSE:
29+
description: The contents of your Unity license file. Store this as a secret
30+
UNITY_EMAIL:
31+
description: The address used for your Unity account
32+
UNITY_PASSWORD:
33+
description: The password for your Unity account. Store this as a secret
34+
2635
runs:
2736
using: composite
2837
steps:

.github/actions/compile/action.yml

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,23 @@
1-
name: compile
2-
description: >
3-
Compiles C# code using `msbuild` into a mod assembly.
4-
This action will install any dependent mods declared in the csproj file and restore NuGet packages.
1+
name: Compile
2+
description: Compiles C# code using `msbuild` into a mod assembly. This action will install any dependent mods declared in the csproj file and restore NuGet packages.
3+
4+
x-env:
5+
KSP_ROOT:
6+
description: The path to use as the root of a KSP instance for CKAN to set-up. If not set, `/tmp/ksp` is used instead.
57

68
inputs:
79
build-configuration:
810
default: Release
9-
description: The project configuration to build. Defaults to `Release`.
11+
description: The project configuration to build.
1012

1113
ksp-zip-url:
1214
default: https://github.com/KSPModdingLibs/KSPLibs/raw/main/KSP-1.12.5.zip
1315
description: >
1416
A url for a zip file that contains the assemblies from the game to link against. This should either be stripped
1517
so that it only contains public interfaces, or encrypted so that the libraries are not being redistributed unprotected.
1618
17-
Defaults to `https://github.com/KSPModdingLibs/KSPLibs/raw/main/KSP-1.12.5.zip` which contains stripped versions
18-
of the libraries and should be suitable for most users. It does not require a password.
19+
Defaults to KSP 1.12.5 with stripped versions
20+
of the libraries which should be suitable for most users. It does not require a password.
1921
2022
ksp-zip-password:
2123
description: >

.github/actions/setup-ckan/action.yml

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
name: Setup CKAN
2-
description: Installs CKAN and sets up a KSP installation
2+
description: Installs [CKAN](https://github.com/KSP-CKAN/CKAN) and sets up a KSP installation
3+
4+
x-env:
5+
KSP_ROOT:
6+
description: The path to use as the root of a KSP instance for CKAN to set-up. If not set, `/tmp/ksp` is used instead.
37

48
inputs:
59
ckan-version:
6-
description: >
7-
CKAN tag to install. set to an empty string to always install the most recent version.
8-
See https://github.com/KSP-CKAN/CKAN/tags for a list of available tags
10+
description: CKAN tag to install. set to an empty string to always install the most recent version. See [the CKAN releases page](https://github.com/KSP-CKAN/CKAN/tags) for a list of available tags
911
default: ''
1012

1113
ckan-repo:
@@ -22,7 +24,7 @@ inputs:
2224
1.8
2325
2426
ckan-filters:
25-
description: CKAN filters to enable. newline-separated
27+
description: File globs to ignore when installing mods. Newline-separated. Defaults to most large asset files included in mods. Set to an empty string if you need the entire mod installed for bundling.
2628
default: |
2729
.dds
2830
.png

.github/actions/update-version/action.yml

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,34 @@
1-
name: update-version
1+
name: Update Version
2+
description: Uses [yaclog](https://yaclog.readthedocs.io/en/latest/index.html) and [yaclog-ksp](https://pypi.org/project/yaclog-ksp/) to update a changelog and get release notes. Then runs `update-version.sh` to replace version tokens in several text files. All modifications will be staged to git but not committed.
23

34
inputs:
45
version-string:
5-
description: a version in the form major.minor.build.patch, OR one of "--major", "--minor", "--patch" to increment based on the most recent entry in the changelog
6-
type: string
6+
description: A version number in major.minor.patch.build form, or one of the special strings `--major` `--minor` `--patch` which will increment the version based on the most recent entry in the changelog file.
7+
required: true
78
template-extension:
8-
type: string
99
default: .versiontemplate
10+
description: Corresponds to the input to `update-version.sh`.
1011
files:
11-
type: string
12+
description: Corresponds to the input to `update-version.sh`.
1213
ksp-build-tools-root:
13-
type: string
1414
default: tmp/kspbuildtools #note this is relative to the *mod*'s repository
15+
description: Where to download `update-version.sh`.
1516
changelog-input-file:
16-
type: string
1717
default: CHANGELOG.md
18+
description: The name of a changelog file to use. Should be formatted according to [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), with a `## Unreleased` section at the top for changes that are pending release. `yaclog release` will be invoked which replaces the `## Unreleased` section with the version number and the date stamp.
1819
changelog-output-file:
19-
type: string
20+
description: If specified, this action will run `yaclog-ksp` on the changelog input file which generates a changelog .cfg file suitable for [Kerbal Changelog](https://github.com/HebaruSan/KerbalChangelog/blob/master/README.md). As such, `changelog-output-file` should be somewhere in your mod's artifact path so that it will be included when the mod is installed.
2021
release-notes-output-file:
21-
type: string
2222
default: tmp/release-notes.md
23+
description: If specified, uses `yaclog` to save the most recent changelog info in Markdown format to this file. This can then be used by the `assemble-release` action.
2324

2425
outputs:
2526
version-string:
2627
value: ${{ steps.result.outputs.version-string }}
28+
description: The final version string
2729
release-notes-output-file:
2830
value: ${{ inputs.release-notes-output-file }}
31+
description: The path to the release notes file
2932

3033
runs:
3134
using: composite

.github/workflows/publish-to-spacedock.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,24 @@ on:
66
spacedock-username:
77
type: string
88
required: true
9+
description: Spacedock login username
910
mod-id:
1011
type: string
1112
required: true
13+
description: ID of the mod we are deploying. Get this from the end of your mod's spacedock URL
1214
release-tag:
1315
type: string
1416
required: false
17+
description: The tag of the release. Will be the same as `inputs.release-tag` unless it was blank.
1518
game-id:
1619
type: string
1720
required: false
1821
default: '3102' # hardcoded to KSP1 gameid. retrieve from https://spacedock.info/api/games
22+
description: ID of the game we are deploying for. This should probably be left as-is for KSP 1.
1923
secrets:
2024
spacedock-password:
2125
required: true
26+
description: Spacedock login password. Store this as a secret!
2227

2328
jobs:
2429
publish-to-spacedock:

.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,6 @@
22
bin
33
obj
44
*.nupkg
5+
6+
# docs
7+
docs/_build

0 commit comments

Comments
 (0)