### Odin Doc Block Format Example

Source: https://github.com/odin-lang/pkg.odin-lang.org.git/blob/master/README.md

Illustrates the required structure for documentation comments in Odin code, including keywords like `Inputs:`, `Returns:`, `Example:`, and `Output:`, along with indentation rules for code and output blocks. This format is processed by the documentation generator.

```Odin
/*
Whether the given string is "example"

**Does not allocate**

Inputs:
- bar: The string to check

Returns:
- ok: A boolean indicating whether bar is "example"

Example:
	foo("example")
	foo("bar")

Output:
	true
	false
*/
foo :: proc(bar: string) -> (ok: bool) {}
```

--------------------------------

### Example Odin Documentation Generator Configuration (JSON)

Source: https://github.com/odin-lang/pkg.odin-lang.org.git/blob/master/README.md

Provides an example configuration file for the Odin documentation generator. This JSONC file defines settings such as hiding core packages, URL prefixes, and collection details including source URLs, base URLs, root paths, licenses, and homepage configuration. Note that comments should be removed for a strictly valid JSON file.

```json
{
	// Hides the core packages from the menu, homepage and search results,
	// they are still there so that links from your own packages work.
	"hide_core": true,
	"hide_base": false,
	// If your docs are going to be on a subpath of your domain, for example: `name.github.io/repo`
	// You can provide a url_prefix here to make the paths line up, if your docs will be at the root of the domain, leave this out.
	"url_prefix": "/repo",
	// This is where you define collections, you will probably have only one.
	"collections": {
		"foo": {
			"name": "foo",
			"source_url": "https://github.com/odin-lang/Odin/blob/main",
			// This URL is the prefix of your collection, core will be at /core, vendor at /vendor.
			// This is prefixed with the url_prefix field above if that is set.
			"base_url": "/foo",
			// The root of the project, because you will probably be in a subdirectory, you can use a relative path.
			// You can also use $ODIN_ROOT which is replaced by the directory that contains the Odin core and vendor collections.
			"root_path": "$ODIN_ROOTfoo",
			"license": {
				"text": "BSD-3-Clause",
				"url": "https://github.com/odin-lang/Odin/tree/master/LICENSE"
			},
			// Configuration for the home page.
			"home": {
				"title": "Foo",
				// The program can turn a readme into HTML and put it on the homepage.
				// The first h1 it finds will be replaced by one with a link and the title above.
				// You can leave this empty and provide a "description" instead.
				"embed_readme": "../../README.md",
				// Instead of embedding the readme, you can provide a simple description.
				"description": "Hello Foo!"
			}
		}
	}
}
```

--------------------------------

### GitHub Actions Workflow for Deploying Odin Docs (YAML)

Source: https://github.com/odin-lang/pkg.odin-lang.org.git/blob/master/README.md

Presents a GitHub Actions workflow definition in YAML for automating the build and deployment of Odin documentation to GitHub Pages. The workflow is triggered on pushes to the main branch or manually, sets necessary permissions, manages concurrency, and includes steps for setting up Odin, installing dependencies, building the generator, checking out the repository, generating documentation, configuring pages, uploading artifacts, and deploying.

```yaml
name: Deploy docs to GitHub pages

# Sets up to deploy when a new commit is pushed to the main branch, or when you click
# run in the GitHub UI.
on:
  push:
    branches: [main]
  workflow_dispatch:

# Upgrade permissions of this workflow to being able to upload to GitHub pages.
permissions:
  contents: read
  pages: write
  id-token: write

# Makes sure there is only one deployment running at a time.
concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  docs:
    # Environment that the action deploys to.
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    steps:
      - name: Setup Odin
        run: |
          sudo apt-get install llvm-14 clang-14
          cd /home/runner
          git clone https://github.com/odin-lang/Odin
          cd Odin
          make
          echo "/home/runner/Odin" >> $GITHUB_PATH

      - name: Get commonmark
        run: sudo apt-get install libcmark-dev

      - name: Get and build Odin docs generator
        run: |
          cd /home/runner
          git clone https://github.com/odin-lang/pkg.odin-lang.org odin-doc
          cd odin-doc
          # The /home/runner/odin directory is in the PATH so output it there.
          odin build . -out:/home/runner/odin/odin-doc
          cd /home/runner

      - uses: actions/checkout@v1

      - name: Generate documentation
        run: |
          cd website

          rm -rf static
          mkdir static

          # Generate the .odin-doc file.
          odin doc path-to-all.odin -file -all-packages -doc-format

          cd static

          # Generate the website using the .odin-doc and the custom configuration.
          odin-doc path-to-all.odin-doc path-to-config.json

          # A requirement for GitHub pages with custom domains.
          echo "your-custom-domain.example.com" > CNAME

      - uses: actions/configure-pages@v3

      - uses: actions/upload-pages-artifact@v2
        with:
          # This should point where you ran the generator.
          path: ./website/static

      - uses: actions/deploy-pages@v2
        id: deployment
```

--------------------------------

### Build and Generate Documentation (Shell)

Source: https://github.com/odin-lang/pkg.odin-lang.org.git/blob/master/README.md

Sequence of shell commands to build the documentation generator binary, create the intermediate `.odin-doc` file from source, and generate the final HTML documentation using a configuration file.

```Shell
odin build . -out:odin-doc
```

```Shell
odin doc path-to-step-1.odin -file -all-packages -doc-format
```

```Shell
odin-doc path-to-.odin-doc path-to-config.json
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.