Skip to content

Commit

Permalink
Add --host docs to docs serve (#5936)
Browse files Browse the repository at this point in the history
## What are you changing in this pull request and why?
Resolves #5573

## Checklist
- [x] Review the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md)
so my content adheres to these guidelines.
- [x] For [docs
versioning](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#about-versioning),
review how to [version a whole
page](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#adding-a-new-version)
and [version a block of
content](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-blocks-of-content).
- [ ] Add a checklist item for anything that needs to happen before this
PR is merged, such as "needs technical review" or "change base branch."

---------

Co-authored-by: Mirna Wong <[email protected]>
  • Loading branch information
mrtns and mirnawong1 authored Aug 28, 2024
1 parent ef4c8e1 commit 285c8f2
Showing 1 changed file with 34 additions and 4 deletions.
38 changes: 34 additions & 4 deletions website/docs/reference/commands/cmd-docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,12 @@ id: "cmd-docs"

The command is responsible for generating your project's documentation website by

1. Copying the website `index.html` file into the `target/` directory
2. Compiling the resources in your project, so that their `compiled_code` will be included in [`manifest.json`](/reference/artifacts/manifest-json)
1. Copying the website `index.html` file into the `target/` directory.
2. Compiling the resources in your project, so that their `compiled_code` will be included in [`manifest.json`](/reference/artifacts/manifest-json).
3. Running queries against database metadata to produce the [`catalog.json`](/reference/artifacts/catalog-json) file, which contains metadata about the tables and <Term id="view">views</Term> produced by the models in your project.

**Example**:

```
dbt docs generate
```
Expand All @@ -24,16 +25,17 @@ dbt docs generate
Use the `--select` argument to limit the nodes included within `catalog.json`. When this flag is provided, step (3) will be restricted to the selected nodes. All other nodes will be excluded. Step (2) is unaffected.

**Example**:

```shell
dbt docs generate --select +orders
```

</VersionBlock>


Use the `--no-compile` argument to skip re-compilation. When this flag is provided, `dbt docs generate` will skip step (2) described above.

**Example**:

```
dbt docs generate --no-compile
```
Expand All @@ -43,26 +45,54 @@ Use the `--empty-catalog` argument to skip running the database queries to popul
This is not recommended for production environments, as it means that your documentation will be missing information gleaned from database metadata (the full set of columns in each table, and statistics about those tables). It can speed up `docs generate` in development, when you just want to visualize lineage and other information defined within your project. To learn how to build your documentation in dbt Cloud, refer to [build your docs in dbt Cloud](/docs/collaborate/build-and-view-your-docs).

**Example**:

```
dbt docs generate --empty-catalog
```

### dbt docs serve
This command starts a webserver on port 8080 to serve your documentation locally and opens the documentation site in your default browser. The webserver is rooted in your `target/` directory. Be sure to run `dbt docs generate` before `dbt docs serve` because the `generate` command produces a [catalog metadata artifact](/reference/artifacts/catalog-json) that the `serve` command depends upon. You will see an error message if the catalog is missing.

This command starts a webserver on port 8080 to serve your documentation locally and opens the documentation site in your default browser. The webserver is rooted in your `target/` directory. Be sure to run `dbt docs generate` before `dbt docs serve` because the `generate` command produces a [catalog metadata artifact](/reference/artifacts/catalog-json) that the `serve` command depends upon. You will see an error message if the catalog is missing.

Use the `dbt docs serve` command if you're developing locally with the [dbt Cloud CLI](/docs/cloud/cloud-cli-installation) or [dbt Core](/docs/core/installation-overview). The [dbt Cloud IDE](/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) doesn't support this command.

**Usage:**

<VersionBlock lastVersion="1.8.1">
```
dbt docs serve [--profiles-dir PROFILES_DIR]
[--profile PROFILE] [--target TARGET]
[--port PORT]
[--no-browser]
```
</VersionBlock>
<VersionBlock firstVersion="1.8.2">
```
dbt docs serve [--profiles-dir PROFILES_DIR]
[--profile PROFILE] [--target TARGET]
[--host HOST]
[--port PORT]
[--no-browser]
```
</VersionBlock>

You may specify a different port using the `--port` flag.

**Example**:

```
dbt docs serve --port 8001
```

<VersionBlock firstVersion="1.8.2">

You may specify a different host using the `--host` flag.

**Example**:

```shell
dbt docs serve --host ""
```

As of 1.8.1, the default host is `127.0.0.1`. For versions 1.8.0 and prior, the default host was `""`.
</VersionBlock>

0 comments on commit 285c8f2

Please sign in to comment.