dandri/continuwuity
1
0
Fork 0
mirror of https://forgejo.ellis.link/continuwuation/continuwuity/ synced 2026-06-04 04:31:22 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

feat: Generate admin command documentation

Browse Source 
The first part of getting admin command docs on the website.

Next is is including it in the same way we do the example config or
readme.

There's also the beginnings of manpage generation here, although it's
kinda sus and I'm not sure how it's supposed to work. I'll leave that to
anyone who wants to package it.

We introduce the beginings of the xtask pattern here - we do a lot of
file generation, I thought it would be best to avoid doing that on every
compilation. It also helps avoid lots of runtime deps.

We'll need to document generating this stuff & probably add pre-commit
hooks for it, though.
This commit is contained in:
Jade Ellis
2025-05-24 00:28:09 +01:00
parent 22c9650c0a
commit 5a66de2633
38 changed files with 2918 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cargo/config.toml
+2
View File
@@ -0,0 +1,2 @@
[alias]
xtask = "run --package xtask --"
Cargo.lock
Generated
+121
View File
@@ -47,12 +47,56 @@ dependencies = [
"alloc-no-stdlib",
]
[[package]]
name = "anstream"
version = "0.6.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8acc5369981196006228e28809f761875c0327210a891e941f4c683b3a99529b"
dependencies = [
"anstyle",
"anstyle-parse",
"anstyle-query",
"anstyle-wincon",
"colorchoice",
"is_terminal_polyfill",
"utf8parse",
]
[[package]]
name = "anstyle"
version = "1.0.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "55cc3b69f167a1ef2e161439aa98aed94e6028e5f9a59be9a6ffb47aef1651f9"
[[package]]
name = "anstyle-parse"
version = "0.2.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3b2d16507662817a6a20a9ea92df6652ee4f94f914589377d69f3b21bc5798a9"
dependencies = [
"utf8parse",
]
[[package]]
name = "anstyle-query"
version = "1.1.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "79947af37f4177cfead1110013d678905c37501914fba0efea834c3fe9a8d60c"
dependencies = [
"windows-sys 0.59.0",
]
[[package]]
name = "anstyle-wincon"
version = "3.0.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6680de5231bd6ee4c6191b8a1325daa282b415391ec9d3a37bd34f2060dc73fa"
dependencies = [
"anstyle",
"once_cell_polyfill",
"windows-sys 0.59.0",
]
[[package]]
name = "anyhow"
version = "1.0.98"
@@ -717,14 +761,25 @@ dependencies = [
"clap_derive",
]
[[package]]
name = "clap-markdown"
version = "0.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d2a2617956a06d4885b490697b5307ebb09fec10b088afc18c81762d848c2339"
dependencies = [
"clap",
]
[[package]]
name = "clap_builder"
version = "4.5.38"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "379026ff283facf611b0ea629334361c4211d1b12ee01024eec1591133b04120"
dependencies = [
"anstream",
"anstyle",
"clap_lex",
"strsim",
]
[[package]]
@@ -745,6 +800,16 @@ version = "0.7.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f46ad14479a25103f283c0f10005961cf086d8dc42205bb44c46ac563475dca6"
[[package]]
name = "clap_mangen"
version = "0.2.26"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "724842fa9b144f9b89b3f3d371a89f3455eea660361d13a554f68f8ae5d6c13a"
dependencies = [
"clap",
"roff",
]
[[package]]
name = "cmake"
version = "0.1.54"
@@ -760,6 +825,12 @@ version = "1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b"
[[package]]
name = "colorchoice"
version = "1.0.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5b63caa9aa9397e2d9480a9b13673856c78d8ac123288526c37d7839f2a86990"
[[package]]
name = "concurrent-queue"
version = "2.5.0"
@@ -2335,6 +2406,12 @@ version = "2.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "469fb0b9cefa57e3ef31275ee7cacb78f2fdca44e4765491884a2b119d4eb130"
[[package]]
name = "is_terminal_polyfill"
version = "1.70.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7943c866cc5cd64cbc25b2e01621d07fa8eb2a1a23160ee81ce38704e97b8ecf"
[[package]]
name = "itertools"
version = "0.12.1"
@@ -2925,6 +3002,12 @@ dependencies = [
"portable-atomic",
]
[[package]]
name = "once_cell_polyfill"
version = "1.70.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a4895175b425cb1f87721b59f0f286c2092bd4af812243672510e1ac53e2e0ad"
[[package]]
name = "openssl-probe"
version = "0.1.6"
@@ -3693,6 +3776,12 @@ dependencies = [
"windows-sys 0.52.0",
]
[[package]]
name = "roff"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "88f8660c1ff60292143c98d08fc6e2f654d722db50410e3f3797d40baaf9d8f3"
[[package]]
name = "ruma"
version = "0.10.1"
@@ -4525,6 +4614,12 @@ dependencies = [
"quote",
]
[[package]]
name = "strsim"
version = "0.11.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
[[package]]
name = "subslice"
version = "0.2.3"
@@ -5256,6 +5351,12 @@ version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
[[package]]
name = "utf8parse"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
[[package]]
name = "uuid"
version = "1.16.0"
@@ -5855,6 +5956,26 @@ dependencies = [
"markup5ever",
]
[[package]]
name = "xtask"
version = "0.5.0-rc.5"
dependencies = [
"clap",
"serde",
"serde_json",
]
[[package]]
name = "xtask-admin-command"
version = "0.5.0-rc.5"
dependencies = [
"clap-markdown",
"clap_builder",
"clap_mangen",
"conduwuit",
"conduwuit_admin",
]
[[package]]
name = "yansi"
version = "1.0.1"
Cargo.toml
+6 -1
View File
@@ -2,7 +2,7 @@
[workspace]
resolver = "2"
members = ["src/*"]
members = ["src/*", "xtask/*"]
default-members = ["src/*"]
[workspace.package]
@@ -639,6 +639,11 @@ package = "conduwuit_build_metadata"
path = "src/build_metadata"
default-features = false
[workspace.dependencies.conduwuit]
package = "conduwuit"
path = "src/main"
###############################################################################
#
# Release profiles
conduwuit-example.toml
+7 -1
View File
@@ -662,12 +662,18 @@
# Enable journald logging on Unix platforms
#
# When enabled, log output will be sent to the systemd journal
# This is only supported on Unix platforms
#
#log_to_journald = false
# The syslog identifier to use with journald logging
#
# Only used when journald logging is enabled
#
#journald_identifier = "conduwuit"
# Defaults to the binary name
#
#journald_identifier =
# OpenID token expiration/TTL in seconds.
#
src/admin/admin.rs
+1 -1
View File
@@ -10,7 +10,7 @@
#[derive(Debug, Parser)]
#[command(name = "conduwuit", version = conduwuit::version())]
pub(super) enum AdminCommand {
pub enum AdminCommand {
#[command(subcommand)]
/// - Commands for managing appservices
Appservices(AppserviceCommand),
src/admin/appservice/mod.rs
+1 -1
View File
@@ -7,7 +7,7 @@
#[derive(Debug, Subcommand)]
#[admin_command_dispatch]
pub(super) enum AppserviceCommand {
pub enum AppserviceCommand {
/// - Register an appservice using its registration YAML
///
/// This command needs a YAML generated by an appservice (such as a bridge),
src/admin/check/mod.rs
+1 -1
View File
@@ -7,6 +7,6 @@
#[admin_command_dispatch]
#[derive(Debug, Subcommand)]
pub(super) enum CheckCommand {
pub enum CheckCommand {
CheckAllUsers,
}
src/admin/debug/mod.rs
+1 -1
View File
@@ -11,7 +11,7 @@
#[admin_command_dispatch]
#[derive(Debug, Subcommand)]
pub(super) enum DebugCommand {
pub enum DebugCommand {
/// - Echo input of admin command
Echo {
message: Vec<String>,
src/admin/debug/tester.rs
+1 -1
View File
@@ -4,7 +4,7 @@
#[admin_command_dispatch]
#[derive(Debug, clap::Subcommand)]
pub(crate) enum TesterCommand {
pub enum TesterCommand {
Panic,
Failure,
Tester,
src/admin/federation/mod.rs
+1 -1
View File
@@ -8,7 +8,7 @@
#[admin_command_dispatch]
#[derive(Debug, Subcommand)]
pub(super) enum FederationCommand {
pub enum FederationCommand {
/// - List all rooms we are currently handling an incoming pdu from
IncomingFederation,
src/admin/media/mod.rs
+3 -3
View File
@@ -9,7 +9,7 @@
#[admin_command_dispatch]
#[derive(Debug, Subcommand)]
pub(super) enum MediaCommand {
pub enum MediaCommand {
/// - Deletes a single media file from our database and on the filesystem
/// via a single MXC URL or event ID (not redacted)
Delete {
@@ -90,10 +90,10 @@ pub(super) enum MediaCommand {
#[arg(short, long, default_value("10000"))]
timeout: u32,
#[arg(short, long, default_value("800"))]
#[arg(long, default_value("800"))]
width: u32,
#[arg(short, long, default_value("800"))]
#[arg(long, default_value("800"))]
height: u32,
},
}
src/admin/mod.rs
+2
View File
@@ -33,6 +33,8 @@
conduwuit::mod_dtor! {}
conduwuit::rustc_flags_capture! {}
pub use crate::admin::AdminCommand;
/// Install the admin command processor
pub async fn init(admin_service: &service::admin::Service) {
_ = admin_service
src/admin/query/account_data.rs
+1 -1
View File
@@ -8,7 +8,7 @@
#[admin_command_dispatch]
#[derive(Debug, Subcommand)]
/// All the getters and iterators from src/database/key_value/account_data.rs
pub(crate) enum AccountDataCommand {
pub enum AccountDataCommand {
/// - Returns all changes to the account data that happened after `since`.
ChangesSince {
/// Full user ID
src/admin/query/appservice.rs
+1 -1
View File
@@ -6,7 +6,7 @@
#[derive(Debug, Subcommand)]
/// All the getters and iterators from src/database/key_value/appservice.rs
pub(crate) enum AppserviceCommand {
pub enum AppserviceCommand {
/// - Gets the appservice registration info/details from the ID as a string
GetRegistration {
/// Appservice registration ID
src/admin/query/globals.rs
+1 -1
View File
@@ -6,7 +6,7 @@
#[derive(Debug, Subcommand)]
/// All the getters and iterators from src/database/key_value/globals.rs
pub(crate) enum GlobalsCommand {
pub enum GlobalsCommand {
DatabaseVersion,
CurrentCount,
src/admin/query/mod.rs
+1 -1
View File
@@ -27,7 +27,7 @@
#[admin_command_dispatch]
#[derive(Debug, Subcommand)]
/// Query tables from database
pub(super) enum QueryCommand {
pub enum QueryCommand {
/// - account_data.rs iterators and getters
#[command(subcommand)]
AccountData(AccountDataCommand),
src/admin/query/presence.rs
+1 -1
View File
@@ -7,7 +7,7 @@
#[derive(Debug, Subcommand)]
/// All the getters and iterators from src/database/key_value/presence.rs
pub(crate) enum PresenceCommand {
pub enum PresenceCommand {
/// - Returns the latest presence event for the given user.
GetPresence {
/// Full user ID
src/admin/query/pusher.rs
+1 -1
View File
@@ -5,7 +5,7 @@
use crate::Context;
#[derive(Debug, Subcommand)]
pub(crate) enum PusherCommand {
pub enum PusherCommand {
/// - Returns all the pushers for the user.
GetPushers {
/// Full user ID
src/admin/query/raw.rs
+1 -1
View File
@@ -19,7 +19,7 @@
#[derive(Debug, Subcommand)]
#[allow(clippy::enum_variant_names)]
/// Query tables from database
pub(crate) enum RawCommand {
pub enum RawCommand {
/// - List database maps
RawMaps,
src/admin/query/resolver.rs
+1 -1
View File
@@ -8,7 +8,7 @@
#[admin_command_dispatch]
#[derive(Debug, Subcommand)]
/// Resolver service and caches
pub(crate) enum ResolverCommand {
pub enum ResolverCommand {
/// Query the destinations cache
DestinationsCache {
server_name: Option<OwnedServerName>,
src/admin/query/room_alias.rs
+1 -1
View File
@@ -7,7 +7,7 @@
#[derive(Debug, Subcommand)]
/// All the getters and iterators from src/database/key_value/rooms/alias.rs
pub(crate) enum RoomAliasCommand {
pub enum RoomAliasCommand {
ResolveLocalAlias {
/// Full room alias
alias: OwnedRoomAliasId,
src/admin/query/room_state_cache.rs
+1 -1
View File
@@ -6,7 +6,7 @@
use crate::Context;
#[derive(Debug, Subcommand)]
pub(crate) enum RoomStateCacheCommand {
pub enum RoomStateCacheCommand {
ServerInRoom {
server: OwnedServerName,
room_id: OwnedRoomId,
src/admin/query/room_timeline.rs
+1 -1
View File
@@ -8,7 +8,7 @@
#[admin_command_dispatch]
#[derive(Debug, Subcommand)]
/// Query tables from database
pub(crate) enum RoomTimelineCommand {
pub enum RoomTimelineCommand {
Pdus {
room_id: OwnedRoomOrAliasId,
src/admin/query/sending.rs
+1 -1
View File
@@ -8,7 +8,7 @@
#[derive(Debug, Subcommand)]
/// All the getters and iterators from src/database/key_value/sending.rs
pub(crate) enum SendingCommand {
pub enum SendingCommand {
/// - Queries database for all `servercurrentevent_data`
ActiveRequests,
src/admin/query/short.rs
+1 -1
View File
@@ -7,7 +7,7 @@
#[admin_command_dispatch]
#[derive(Debug, Subcommand)]
/// Query tables from database
pub(crate) enum ShortCommand {
pub enum ShortCommand {
ShortEventId {
event_id: OwnedEventId,
},
src/admin/query/users.rs
+1 -1
View File
@@ -8,7 +8,7 @@
#[admin_command_dispatch]
#[derive(Debug, Subcommand)]
/// All the getters and iterators from src/database/key_value/users.rs
pub(crate) enum UsersCommand {
pub enum UsersCommand {
CountUsers,
IterUsers,
src/admin/room/alias.rs
+1 -1
View File
@@ -8,7 +8,7 @@
use crate::Context;
#[derive(Debug, Subcommand)]
pub(crate) enum RoomAliasCommand {
pub enum RoomAliasCommand {
/// - Make an alias point to a room.
Set {
#[arg(short, long)]
src/admin/room/directory.rs
+1 -1
View File
@@ -6,7 +6,7 @@
use crate::{Context, PAGE_SIZE, get_room_info};
#[derive(Debug, Subcommand)]
pub(crate) enum RoomDirectoryCommand {
pub enum RoomDirectoryCommand {
/// - Publish a room to the room directory
Publish {
/// The room id of the room to publish
src/admin/room/info.rs
+1 -1
View File
@@ -7,7 +7,7 @@
#[admin_command_dispatch]
#[derive(Debug, Subcommand)]
pub(crate) enum RoomInfoCommand {
pub enum RoomInfoCommand {
/// - List joined members in a room
ListJoinedMembers {
room_id: OwnedRoomId,
src/admin/room/mod.rs
+1 -1
View File
@@ -16,7 +16,7 @@
#[admin_command_dispatch]
#[derive(Debug, Subcommand)]
pub(super) enum RoomCommand {
pub enum RoomCommand {
/// - List all rooms the server knows about
#[clap(alias = "list")]
ListRooms {
src/admin/room/moderation.rs
+1 -1
View File
@@ -12,7 +12,7 @@
#[admin_command_dispatch]
#[derive(Debug, Subcommand)]
pub(crate) enum RoomModerationCommand {
pub enum RoomModerationCommand {
/// - Bans a room from local users joining and evicts all our local users
/// (including server
/// admins)
src/admin/server/mod.rs
+1 -1
View File
@@ -9,7 +9,7 @@
#[admin_command_dispatch]
#[derive(Debug, Subcommand)]
pub(super) enum ServerCommand {
pub enum ServerCommand {
/// - Time elapsed since startup
Uptime,
src/admin/user/mod.rs
+1 -1
View File
@@ -8,7 +8,7 @@
#[admin_command_dispatch]
#[derive(Debug, Subcommand)]
pub(super) enum UserCommand {
pub enum UserCommand {
/// - Create a new user
#[clap(alias = "create")]
CreateUser {
xtask/generate-admin-command/Cargo.toml
+26
View File
@@ -0,0 +1,26 @@
[package]
name = "xtask-admin-command"
authors.workspace = true
categories.workspace = true
description.workspace = true
edition.workspace = true
homepage.workspace = true
keywords.workspace = true
license.workspace = true
readme.workspace = true
repository.workspace = true
rust-version.workspace = true
version.workspace = true
[dependencies]
clap-markdown = "0.1.5"
clap_builder = { version = "4.5.38", default-features = false }
clap_mangen = "0.2"
conduwuit-admin.workspace = true
# Hack to prevent rebuilds
conduwuit.workspace = true
[lints]
workspace = true
xtask/generate-admin-command/admin.md
+2633
View File
File diff suppressed because it is too large Load Diff
xtask/generate-admin-command/src/main.rs
+58
View File
@@ -0,0 +1,58 @@
use std::{
fs::{self, File},
io,
path::Path,
};
use clap_builder::{Command, CommandFactory};
use conduwuit_admin::AdminCommand;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut args = std::env::args().skip(1);
let task = args.next();
match task {
| None => todo!(),
| Some(t) => match t.as_str() {
| "man" => {
let dir = Path::new("./admin-man");
gen_manpages(dir)?;
},
| "md" => {
let command = AdminCommand::command().name("admin");
let res = clap_markdown::help_markdown_command_custom(
&command,
&clap_markdown::MarkdownOptions::default(),
);
println!("{res}");
},
| invalid => return Err(format!("Invalid task name: {invalid}").into()),
},
}
Ok(())
}
fn gen_manpages(dir: &Path) -> Result<(), io::Error> {
fn r#gen(dir: &Path, c: &Command, prefix: Option<&str>) -> Result<(), io::Error> {
fs::create_dir_all(dir)?;
let sub_name = c.get_display_name().unwrap_or_else(|| c.get_name());
let name = if let Some(prefix) = prefix {
format!("{prefix}-{sub_name}")
} else {
sub_name.to_owned()
};
let mut out = File::create(dir.join(format!("{name}.1")))?;
let clap_mangen = clap_mangen::Man::new(c.to_owned().disable_help_flag(true));
clap_mangen.render(&mut out)?;
for sub in c.get_subcommands() {
r#gen(&dir.join(sub_name), sub, Some(&name))?;
}
Ok(())
}
r#gen(dir, &AdminCommand::command().name("admin"), None)
}
xtask/main/Cargo.toml
+22
View File
@@ -0,0 +1,22 @@
[package]
name = "xtask"
authors.workspace = true
categories.workspace = true
description.workspace = true
edition.workspace = true
homepage.workspace = true
keywords.workspace = true
license.workspace = true
readme.workspace = true
repository.workspace = true
rust-version.workspace = true
version.workspace = true
[dependencies]
clap.workspace = true
# Required for working with JSON output from cargo metadata
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
[lints]
workspace = true
xtask/main/src/main.rs
+11
View File
@@ -0,0 +1,11 @@
use std::{env, process::Command};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut child = Command::new("cargo").args(["run", "--package", "xtask-admin-command", "--"].into_iter().map(ToOwned::to_owned).chain(env::args().skip(2)))
// .stdout(Stdio::piped())
// .stderr(Stdio::piped())
.spawn()
.expect("failed to execute child");
child.wait()?;
Ok(())
}