Automatic Markdown documentation for SourceMod plugin ConVars.
This action will scan all your SourcePawn code files (specified by --code_patterns regex) for ConVars created by CreateConVar, then look for the first Markdown file matching the --doc_patterns regex, and from within it, look for the first Markdown header matching the --header_patterns regex, and replace that header's contents with the parsed cvar info.
To get started, copy the docs.yml GitHub action from the example.
This action follows SemVer, and offers binding to the latest major version, using:
uses: Rainyan/action-sp-cvar-docs@vNwhere N is the latest major tag.
The action will accept all of the optional arguments for the underlying document.py script as input parameters. For any multi-word arguments, replace any dashes with underlines for the input parameters.
usage: document.py [-h] [-C CODE_PATTERNS] [-D DOC_PATTERNS] [-H HEADER_PATTERNS] [--dry-run] [--encoding ENCODING] [--format-filename FORMAT_FILENAME] [--format-cvarname FORMAT_CVARNAME]
[--format-cvarprop FORMAT_CVARPROP]
cwd
Automatic Markdown documentation for SourceMod plugin ConVars.
positional arguments:
cwd Current working directory.
options:
-h, --help show this help message and exit
-C CODE_PATTERNS, --code_patterns CODE_PATTERNS
RegEx pattern for code files to match.
-D DOC_PATTERNS, --doc_patterns DOC_PATTERNS
RegEx pattern for documentation files to match.
-H HEADER_PATTERNS, --header_patterns HEADER_PATTERNS
RegEx pattern for documentation headers to match for the location of the cvar docs placeholder.
--dry-run If set, print the output to stdout instead of writing to file.
--encoding ENCODING Encoding to use for file read/write operations.
--format-filename FORMAT_FILENAME
Formatting for the code file name, with placeholder !a!. This is skipped if parsing one single code file.
--format-cvarname FORMAT_CVARNAME
Formatting for the cvar name, with placeholder !a!.
--format-cvarprop FORMAT_CVARPROP
Formatting for the cvar property, with placeholder !a! (property name), and !b! (property default value).
For example:
with:
dry_run: truewould use the --dry-run mode, which only prints the change to stdout instead of writing it to file, and:
with:
format_cvarname: '* **!a!**\n'would render the cvar name (!a!) with **bold**.
For the input arguments' default values, see the argument parser code.
Using the file .github/workflows/docs.yml at the root of the repo:
name: Update cvar docs
# Controls when the workflow will run
on:
# Triggers the workflow on pull request events but only for the main branch
pull_request:
branches: [ main, master ]
paths:
- '.github/workflows/docs.yml'
- '*.sp'
- '*.inc'
- '*.md'
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
jobs:
update-docs:
permissions:
contents: write
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Update docs
uses: Rainyan/action-sp-cvar-docs@v3Assuming there exists an example.sp file in the repo:
#include <sourcemod>
ConVar foo;
public void OnPluginStart()
{
foo = CreateConVar("foo", "The default value", "This variable adjusts the foo.",
_, true, 0.0, true, float(MaxClients));
}And there exists a README.md file at the root of the repo:
# Test
Lorem ipsum.
## Usage
<!-- A header at any level will work, as long as it matches the --header_patterns regex -->
### Cvars
This line will be replaced.
This line will also be replaced.
### But the following header will persist.
As will the text after it.The action will update the README.md file:
# Test
Lorem ipsum.
## Usage
<!-- A header at any level will work, as long as it matches the --header_patterns regex -->
### Cvars
* foo
* Default value: `The default value`
* Description: `This variable adjusts the foo.`
* Min: `0.0`
* Max: `float(MaxClients)`
### But the following header will persist.
As will the text after it.PRs are most welcome! I'm mostly using this for my personal projects, but am publishing it here in case someone else also finds it useful. If you have any ideas on how to improve this tool, please do consider submitting a patch.
SourceMod Cvar Docs is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.
SourceMod Cvar Docs is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.