GI-DOCGEN(1)

✨ GI-DOCGEN 💅 (section 1 of the manual, bestie)

okay so you found gi-docgen and you're about to have the cutest little API docs, no cap. this is the manual page for the gi-docgen user command, and it's gonna be a whole journey. grab a strawberry 🍓 and let's go.

---

🎀 NAME 🎀

gi-docgen — a documentation generator using gobject-introspection. literally that's her whole job description and she ATE.

---

🌸 SYNOPSIS 🌸

gi-docgen COMMAND [OPTION...] GIR_FILE

---

🦋 DESCRIPTION 🦋

GI-DocGen is a document generator for GObject-based libraries. GObject is the base type system of the GNOME project. GI-DocGen uses the machine readable introspection data provided by GObject-based libraries in order to generate the API reference of these libraries, as well as other ancillary documentation.

The main gi-docgen executable provides various subcommands to access all its functionality.

it's giving "one binary, many little side quests" 💖

---

👑 Common options 👑

All commands have the following options — yes, all of them, they're the shared besties:

• --quiet — do not print details of the current operation. shhh, she's being mysterious 🤫
• --fatal-warnings — make warnings fatal errors. dramatic? yes. effective? also yes 💀
• --help — print command line help. the classic, the icon, the moment ✨

---

💜 The generate command 💜

The generate command provides the main functionality of gi-docgen. she's the main character, fr fr 👑

gi-docgen generate [ OPTIONS ] [ GIR_FILE ]

The generate command will parse the given GIR file, as well as its dependencies, and build an API reference for the namespace it finds in the introspection data. Projects can use a configuration file to control aspects of the output, as well as provide additional content that should be included in the documentation.

🌈 options:

• --config=FILE — use the given project configuration file
• --content-dir=PATH — specify the directory where the content files listed in the project configuration file can be found
• --templates-dir=PATH — specify the directory where the templates used to generate the documentation can be found
• --theme-name=NAME — specify the template name to be used when generating the documentation, overriding the project's configuration
• --output-dir=PATH — create the documentation under the given directory
• --no-namespace-dir — generate all documentation files directly under the output directory, instead of creating a directory using the namespace name and version. flat structure enjoyers rise 🙈
• --add-include-path=PATH — add a directory to the path which the scanner uses to find GIR files. Can be used multiple times to specify multiple directories
• --section=NAME — generate the documentation only for the given section. Can be used multiple times to specify multiple sections. The supported sections are aliases, bitfields, classes, domains, enums, interfaces, structs and unions. Special values are all, meaning all sections (the default); and none, meaning no section. pick your faves, it's a vibe check 🎀
• --dry-run — parse the GIR_FILE without generating the documentation. window shopping, we love to see it 💅

---

🧚 The gen-index command 🧚

The gen-index command generates an index of symbols and terms that can be used to search inside the documentation generated by gi-docgen. it's the search bar of your dreams.

gi-docgen gen-index [ OPTIONS ] [ GIR_FILE ]

The generated index is a JSON formatted file is called index.json.

🌈 options:

• --config=FILE — use the given project configuration file
• --content-dir=PATH — specify the directory where the content files listed in the project configuration file can be found
• --output-dir=PATH — create the index under the given directory
• --add-include-path=PATH — add a directory to the path which the scanner uses to find GIR files. Can be used multiple times to specify multiple directories
• --dry-run — parse the GIR_FILE without generating the documentation

---

🫶 The check command 🫶

The check command runs a series of checks on the introspection file, to verify that public API is properly documented. It can be used as part of a test suite. she's the friend who proofreads your essay before you submit it 😭💖

gi-docgen check [ OPTIONS ] [ GIR_FILE ]

🌈 options:

• --config=FILE — use the given project configuration file
• --add-include-path=PATH — add a directory to the path which the scanner uses to find GIR files. Can be used multiple times to specify multiple directories

---

🔥 The serve command 🔥

The serve command generates an API reference and serves it using a local HTTP server. docs + localhost = the sleepover 🎀

gi-docgen serve [ OPTIONS ] [ GIR_FILE ]

The serve command will parse the given GIR file, as well as its dependencies, and build an API reference for the namespace it finds in the introspection data. Once the reference has been built successfully, gi-docgen will start a local HTTP server pointing at the output directory.

🌈 options:

• --bind=ADDRESS — use the given address for the HTTP server; the default is 127.0.0.1
• --port=PORT — use the given port for the HTTP server; the default is 8080

---

⭐ The help command ⭐

The help command prints out the command line help. If you don't specify any command or option when invoking gi-docgen, the help command will be implied. she's always there for you, lurking, ready 🫶

gi-docgen help [ OPTIONS ] [ COMMAND ]

If no command is specified, help will print out the list of commands.

If a command is specified, help will print out the command line help for that program.

🌈 options:

• --version — print out the version of gi-docgen

---

💀 EXIT STATUS 💀

• 0 — The command was successful. slay ✅
• 1 — Error, or warning, was generated. not slay 😭

---

🌱 ENVIRONMENT VARIABLES 🌱

The gi-docgen executable uses the XDG_DATA_DIRS and XDG_DATA_HOME environment variables to search for introspection data included in the GIR file.

If the GIDOCGEN_DEBUG environment variable is set, gi-docgen will print out additional messages, which can be helpful when debugging issues. turn it on when things get weird, iykyk 🦋

---

🌟 SEE ALSO 🌟

• GI-DocGen: http://gnome.pages.gitlab.gnome.org/gi-docgen/
• GObject-Introspection: https://gi.readthedocs.org/
• GObject: https://developer.gnome.org/gobject/

---

and that's the whole page bestie, you're officially caught up 💖 this manual came to you from gi-docgen 2021.3 (that's the source + version, the whole pedigree 🎀) and she's filed under GI-DOCGEN(1) like the legend she is. periodt ✨