From 50c0e81643f3689f16c590e2ef6be1d551070c4d Mon Sep 17 00:00:00 2001 From: Max Erenberg <> Date: Mon, 27 Sep 2021 08:48:55 -0400 Subject: [PATCH] add man pages --- .gitignore | 2 + docs/README.md | 23 +++++++ docs/ceo.1.scd | 29 ++++++++ docs/ceo.ini.5.scd | 57 ++++++++++++++++ docs/ceod.ini.5.scd | 159 ++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 270 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/ceo.1.scd create mode 100644 docs/ceo.ini.5.scd create mode 100644 docs/ceod.ini.5.scd diff --git a/.gitignore b/.gitignore index 8e5f25d..e0073cf 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,5 @@ __pycache__/ *.o *.so .idea/ +/docs/*.1 +/docs/*.5 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..64aadda --- /dev/null +++ b/docs/README.md @@ -0,0 +1,23 @@ +# Documentation +## OpenAPI +We are using [OpenAPI 3.0](https://swagger.io/docs/specification/about/) to +document the REST API for ceod, and [Redoc](https://github.com/Redocly/redoc) +to generate HTML documentation from the OpenAPI file. + +First, make sure you have Node.js and npm installed. Then, install the Redoc CLI: +```sh +npm install -g redoc-cli +``` +After you make changes to the openapi.yaml file, make sure to regenerate the HTML: +```sh +redoc-cli bundle openapi.yaml +``` +You can now view the [redoc-static.html](./redoc-static.html) file from your browser. + +## Man pages +We are using [scdoc](https://git.sr.ht/~sircmpwn/scdoc) to generate our man pages. +You can view the pages from your terminal like so: +```sh +scdoc < ceo.1.scd > ceo.1 +man ./ceo.1 +``` diff --git a/docs/ceo.1.scd b/docs/ceo.1.scd new file mode 100644 index 0000000..08f3b26 --- /dev/null +++ b/docs/ceo.1.scd @@ -0,0 +1,29 @@ +ceo(1) + +# NAME + +ceo - CSC Electronic Office + +# SYNOPSIS + +*Text User Interface* + *ceo* + +*Command Line Interface* + *ceo* [OPTIONS] COMMAND [ARGS]... + +# DESCRIPTION +CSC Electronic Office is used to manage membership registration and user accounts for the Computer Science Club. + +To use the TUI, type *ceo* with no arguments. +To use the CLI, run *ceo --help*. + +# SEE ALSO + +*ceo.ini*(5), *ceod.ini*(5) + +# AUTHORS + +Max Erenberg ++ +Andrew Wang ++ +Rio Liu diff --git a/docs/ceo.ini.5.scd b/docs/ceo.ini.5.scd new file mode 100644 index 0000000..1b823bc --- /dev/null +++ b/docs/ceo.ini.5.scd @@ -0,0 +1,57 @@ +ceo.ini(5) + +# NAME + +ceo.ini - configuration file for ceo + +# SYNOPSIS + +/etc/csc/ceo.ini + +# DESCRIPTION + +ceo.ini is an INI file with various sections which control the behaviour of *ceo*(1). + +# DEFAULTS SECTION + _base_domain_++ + The domain name of CSC. Should be set to 'csclub.uwaterloo.ca'. + + _uw_domain_++ + The domain of UW. Should be set to 'uwaterloo.ca'. + +# CEOD SECTION + _admin_host_++ + The host with the ceod/admin Kerberos key. + + _database_host_++ + The host with the root password for MySQL and PostgreSQL. + + _mailman_host_++ + The host running Mailman. + + _use_https_++ + Whether to use HTTPS when connecting to ceod. Should be set to 'true'. + + _port_++ + The port on which ceod is listening. + +# POSITIONS SECTION + _required_++ + A comma-separated list of executive positions which must be fulfilled. + + _available_++ + A comma-separated list of available executive positions. + +# MYSQL SECTION + _host_++ + The host where MySQL is running. + +# POSTGRESQL SECTION + _host_++ + The host where PostgreSQL is running. + +# SEE ALSO +*ceo*(1) + +# AUTHORS +Max Erenberg diff --git a/docs/ceod.ini.5.scd b/docs/ceod.ini.5.scd new file mode 100644 index 0000000..e713199 --- /dev/null +++ b/docs/ceod.ini.5.scd @@ -0,0 +1,159 @@ +ceod.ini(5) + +# NAME + +ceod.ini - configuration file for ceod + +# SYNOPSIS + +/etc/csc/ceod.ini + +# DESCRIPTION + +ceod.ini is an INI file with various sections which control the behaviour of ceod. + +# DEFAULTS SECTION + _base_domain_++ + The domain name of CSC. Should be set to 'csclub.uwaterloo.ca'. + +# CEOD SECTION + _admin_host_++ + The host with the ceod/admin Kerberos key. + + _fs_root_host_++ + The host without NFS root squashing. + + _database_host_++ + The host with the root password for MySQL and PostgreSQL. + + _mailman_host_++ + The host running Mailman. + + _use_https_++ + Whether to use HTTPS when connecting to ceod. Should be set to 'true'. + + _port_++ + The port on which ceod is listening. + +# LDAP SECTION + _admin_principal_++ + The Kerberos principal which ceod should use for *kadmin*(1). + + _server_url_++ + The primary CSC LDAP server URL. + + _sasl_realm_++ + The CSC SASL realm for LDAP. Should be 'CSCLUB.UWATERLOO.CA'. + + _users_base_++ + The LDAP OU where users are stored. + + _groups_base_++ + The LDAP OU where groups are stored. + + _sudo_base_++ + The LDAP OU where *sudo*(8) roles are stored. + +# UWLDAP SECTION + _server_url_++ + The UW LDAP server URL. + + _base_++ + The LDAP OU where users are stored in the UW LDAP. + +# MEMBERS SECTION + _min_id_++ + The minimum UID number for members. + + _max_id_++ + The maximum UID number for members. + + _home_++ + The directory in which new members' home directories should be created. + + _skel_++ + The skeleton directory for new members. + +# CLUBS SECTION + _min_id_++ + The minimum UID number for club accounts. + + _max_id_++ + The maximum UID number for club accounts. + + _home_++ + The directory in which new club accounts' home directories should be created. + + _skel_++ + The skeleton directory for new club accounts. + +# MAIL SECTION + _smtp_url_++ + The SMTP URL where ceod should send emails. + + _smtp_starttls_++ + Whether ceod should use STARTTLS with the SMTP server or not. + +# MAILMAN3 SECTION + _api_base_url_++ + The base URL of the Mailman 3 API. + + _api_username_++ + The username to use when authenticating to the Mailman 3 API via HTTP Basic Auth. + + _api_password_++ + The password to use when authenticating to the Mailman 3 API via HTTP Basic Auth. + + _new_member_list_++ + The mailing list to which new members should be subscribed. + +# AUXILIARY GROUPS SECTION + Each key in this section contains a comma-separated list of auxiliary groups to + which members should be added when joining the primary group. For example, + + syscom = office,staff + + means that when someone joins the syscom group, they will also be added to the + office and staff groups. + +# AUXILIARY MAILING LISTS SECTION + Each key in this section contains a comma-separated list of auxiliary mailing lists to + which members should be subscribed when joining the primary group. For example, + + syscom = syscom,syscom-alerts + + means that when someone joins the syscom group, they will also be subscribed to the + syscom and syscom-alerts mailing lists. + +# POSITIONS SECTION + _required_++ + A comma-separated list of executive positions which must be fulfilled. + + _available_++ + A comma-separated list of available executive positions. + +# MYSQL SECTION + _host_++ + The host where MySQL is running. + + _username_++ + The username to use when connecting to MySQL. + + _password_++ + The password to use when connecting to MySQL. + +# POSTGRESQL SECTION + _host_++ + The host where PostgreSQL is running. + + _username_++ + The username to use when connecting to PostgreSQL. + + _password_++ + The password to use when connecting to PostgreSQL. + +# SEE ALSO +*ceo.ini*(5) + +# AUTHORS +Max Erenberg