Document cargo doc --publish-dir

Author: basile-henry

src/doc/man/cargo-doc.md

@@ -27,6 +27,16 @@ or use the [`doc.browser`](../reference/config.html#docbrowser) configuration
 option.
 {{/option}}
 
+{{#option "`--publish-dir`" }}
+The generated documentation will be copied to the specified publish directory.
+This can be used to publish documentation straight into, for example, a
+directory that is being served up by a local web server already.
+This will override the corresponding
+[`doc.publish-dir`](../reference/config.html#docpublish-dir) configuration option and
+[`CARGO_DOC_PUBLISH_DIR`](../reference/environment-variables.html#configuration-environment-variables)
+environment variable.
+{{/option}}
+
 {{#option "`--no-deps`" }}
 Do not build documentation for dependencies.
 {{/option}}

src/doc/man/cargo-rustdoc.md

@@ -39,6 +39,16 @@ or use the [`doc.browser`](../reference/config.html#docbrowser) configuration
 option.
 {{/option}}
 
+{{#option "`--publish-dir`" }}
+The generated documentation will be copied to the specified publish directory.
+This can be used to publish documentation straight into, for example, a
+directory that is being served up by a local web server already.
+This will override the corresponding
+[`doc.publish-dir`](../reference/config.html#docpublish-dir) configuration option and
+[`CARGO_DOC_PUBLISH_DIR`](../reference/environment-variables.html#configuration-environment-variables)
+environment variable.
+{{/option}}
+
 {{/options}}
 
 {{> section-options-package }}

src/doc/man/generated_txt/cargo-doc.txt

@@ -19,6 +19,16 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html#docbrowser>
            configuration option.
 
+       --publish-dir
+           The generated documentation will be copied to the specified publish
+           directory. This can be used to publish documentation straight into,
+           for example, a directory that is being served up by a local web
+           server already. This will override the corresponding doc.publish-dir
+           <https://doc.rust-lang.org/cargo/reference/config.html#docpublish-dir>
+           configuration option and CARGO_DOC_PUBLISH_DIR
+           <https://doc.rust-lang.org/cargo/reference/environment-variables.html#configuration-environment-variables>
+           environment variable.
+
        --no-deps
            Do not build documentation for dependencies.
 

src/doc/man/generated_txt/cargo-rustdoc.txt

@@ -38,6 +38,16 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html#docbrowser>
            configuration option.
 
+       --publish-dir
+           The generated documentation will be copied to the specified publish
+           directory. This can be used to publish documentation straight into,
+           for example, a directory that is being served up by a local web
+           server already. This will override the corresponding doc.publish-dir
+           <https://doc.rust-lang.org/cargo/reference/config.html#docpublish-dir>
+           configuration option and CARGO_DOC_PUBLISH_DIR
+           <https://doc.rust-lang.org/cargo/reference/environment-variables.html#configuration-environment-variables>
+           environment variable.
+
    Package Selection
        By default, the package in the current working directory is selected.
        The -p flag can be used to choose a different package in a workspace.

src/doc/src/commands/cargo-doc.md

@@ -27,6 +27,16 @@ or use the <a href="../reference/config.html#docbrowser"><code>doc.browser</code
 option.</dd>
 
 
+<dt class="option-term" id="option-cargo-doc---publish-dir"><a class="option-anchor" href="#option-cargo-doc---publish-dir"></a><code>--publish-dir</code></dt>
+<dd class="option-desc">The generated documentation will be copied to the specified publish directory.
+This can be used to publish documentation straight into, for example, a
+directory that is being served up by a local web server already.
+This will override the corresponding
+<a href="../reference/config.html#docpublish-dir"><code>doc.publish-dir</code></a> configuration option and
+<a href="../reference/environment-variables.html#configuration-environment-variables"><code>CARGO_DOC_PUBLISH_DIR</code></a>
+environment variable.</dd>
+
+
 <dt class="option-term" id="option-cargo-doc---no-deps"><a class="option-anchor" href="#option-cargo-doc---no-deps"></a><code>--no-deps</code></dt>
 <dd class="option-desc">Do not build documentation for dependencies.</dd>
 

src/doc/src/commands/cargo-rustdoc.md

@@ -43,6 +43,16 @@ or use the <a href="../reference/config.html#docbrowser"><code>doc.browser</code
 option.</dd>
 
 
+<dt class="option-term" id="option-cargo-rustdoc---publish-dir"><a class="option-anchor" href="#option-cargo-rustdoc---publish-dir"></a><code>--publish-dir</code></dt>
+<dd class="option-desc">The generated documentation will be copied to the specified publish directory.
+This can be used to publish documentation straight into, for example, a
+directory that is being served up by a local web server already.
+This will override the corresponding
+<a href="../reference/config.html#docpublish-dir"><code>doc.publish-dir</code></a> configuration option and
+<a href="../reference/environment-variables.html#configuration-environment-variables"><code>CARGO_DOC_PUBLISH_DIR</code></a>
+environment variable.</dd>
+
+
 </dl>
 
 ### Package Selection

src/doc/src/reference/config.md

@@ -78,6 +78,8 @@ pipelining = true             # rustc pipelining
 [doc]
 browser = "chromium"          # browser to use with `cargo doc --open`,
                               # overrides the `BROWSER` environment variable
+publish-dir = "/var/www/html" # directory to copy the generated documentation to
+                              # overrides the `CARGO_DOC_PUBLISH_DIR` environment variable
 
 [env]
 # Set ENV_VAR_NAME=value for any process run by Cargo
@@ -458,6 +460,18 @@ This option sets the browser to be used by [`cargo doc`], overriding the
 `BROWSER` environment variable when opening documentation with the `--open`
 option.
 
+##### `doc.publish-dir`
+
+* Type: string
+* Default: `CARGO_DOC_PUBLISH_DIR` environment variable, or, if that is
+  missing, documentation is not published.
+
+This option is used by [`cargo doc`] as a directory to copy the generated
+documentation to, overriding the `CARGO_DOC_PUBLISH_DIR` environment variable.
+It can also be set with the `--publish-dir` CLI option.
+This can be used to publish documentation straight into, for example, a
+directory that is being served up by a local web server already.
+
 #### `[cargo-new]`
 
 The `[cargo-new]` table defines defaults for the [`cargo new`] command.

src/doc/src/reference/environment-variables.md

@@ -118,6 +118,7 @@ supported environment variables are:
 * `CARGO_TERM_COLOR` — The default color mode, see [`term.color`].
 * `CARGO_TERM_PROGRESS_WHEN` — The default progress bar showing mode, see [`term.progress.when`].
 * `CARGO_TERM_PROGRESS_WIDTH` — The default progress bar width, see [`term.progress.width`].
+* `CARGO_DOC_PUBLISH_DIR` — Directory to copy the generated documentation to, see [`doc.publish-dir`] for more details.
 
 [`cargo doc`]: ../commands/cargo-doc.md
 [`cargo install`]: ../commands/cargo-install.md
@@ -141,6 +142,7 @@ supported environment variables are:
 [`build.dep-info-basedir`]: config.md#builddep-info-basedir
 [`build.pipelining`]: config.md#buildpipelining
 [`doc.browser`]: config.md#docbrowser
+[`doc.publish-dir`]: config.md#docpublish-dir
 [`cargo-new.name`]: config.md#cargo-newname
 [`cargo-new.email`]: config.md#cargo-newemail
 [`cargo-new.vcs`]: config.md#cargo-newvcs

src/etc/man/cargo-doc.1

@@ -21,6 +21,17 @@ or use the \fI\f(BIdoc.browser\fI\fR <https://doc.rust\-lang.org/cargo/reference
 option.
 .RE
 .sp
+\fB\-\-publish\-dir\fR
+.RS 4
+The generated documentation will be copied to the specified publish directory.
+This can be used to publish documentation straight into, for example, a
+directory that is being served up by a local web server already.
+This will override the corresponding
+\fI\f(BIdoc.publish\-dir\fI\fR <https://doc.rust\-lang.org/cargo/reference/config.html#docpublish\-dir> configuration option and
+\fI\f(BICARGO_DOC_PUBLISH_DIR\fI\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html#configuration\-environment\-variables>
+environment variable.
+.RE
+.sp
 \fB\-\-no\-deps\fR
 .RS 4
 Do not build documentation for dependencies.

src/etc/man/cargo-rustdoc.1

@@ -36,6 +36,17 @@ browser unless you define another one in the \fBBROWSER\fR environment variable
 or use the \fI\f(BIdoc.browser\fI\fR <https://doc.rust\-lang.org/cargo/reference/config.html#docbrowser> configuration
 option.
 .RE
+.sp
+\fB\-\-publish\-dir\fR
+.RS 4
+The generated documentation will be copied to the specified publish directory.
+This can be used to publish documentation straight into, for example, a
+directory that is being served up by a local web server already.
+This will override the corresponding
+\fI\f(BIdoc.publish\-dir\fI\fR <https://doc.rust\-lang.org/cargo/reference/config.html#docpublish\-dir> configuration option and
+\fI\f(BICARGO_DOC_PUBLISH_DIR\fI\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html#configuration\-environment\-variables>
+environment variable.
+.RE
 .SS "Package Selection"
 By default, the package in the current working directory is selected. The \fB\-p\fR
 flag can be used to choose a different package in a workspace.