doc: Adopt intra doc links #803
Conversation
|
I'm going to change all occurrences, and then merge this. |
* master: ref(server): Remove legacy id fallback (#800)
relay-common/src/metrics.rs
Outdated
| @@ -407,6 +404,8 @@ pub trait GaugeMetric { | |||
| } | |||
|
|
|||
| /// Emits a metric. | |||
| /// | |||
| /// See [module-level documentation](metrics/index.html) for examples. | |||
There was a problem hiding this comment.
you can also refer to modules by intra-doc syntax
There was a problem hiding this comment.
Strange, I tried this in the top-level Relay binary, but it didn't work there. Let me try again.
There was a problem hiding this comment.
So, I got this to work in cases where the module is imported, but not for extern crates, for instance. Any advice on how to import that?
| @@ -13,14 +13,19 @@ jobs: | |||
| name: Cargo Docs | |||
| runs-on: ubuntu-latest | |||
|
|
|||
| env: | |||
| RUSTDOCFLAGS: -Dbroken_intra_doc_links | |||
There was a problem hiding this comment.
To avoid killing the build cache, you could use cargo rustdoc -- -D broken_intra_doc_links. Since you only ever run cargo doc once, it might not matter though.
There was a problem hiding this comment.
this does store the rust cache across runs with the swatinem/rust-cache@v1 action. How does the env vs the cmdline arg affect the cache?
There was a problem hiding this comment.
RUSTDOCFLAGS is like RUSTFLAGS: whenever it changes, cargo assumes the whole build cache must be invalidated and effectively runs rm -rf target/doc. If you pass flags through rustdoc, it will only rebuild your crates, not your dependencies.
That said, I don't know how to make cargo rustdoc work with workspaces.
There was a problem hiding this comment.
That and it doesn't offer --no-deps, at least from what I remember. That's why we went with RUSTDOCFLAGS. It works well, since we store the build cache only between docs builds, so the flags never change between builds and the cache is not pruned.
| //! [`relay-auth`]: ../relay_auth/index.html | ||
| //! [`relay-cabi`]: ../relay_cabi/index.html | ||
| //! [`relay-common`]: ../relay_common/index.html | ||
| //! [`relay-config`]: ../relay_config/index.html | ||
| //! [`relay-ffi`]: ../relay_ffi/index.html | ||
| //! [`relay-ffi-macros`]: ../relay_ffi_macros/index.html | ||
| //! [`relay-filter`]: ../relay_filter/index.html | ||
| //! [`relay-general`]: ../relay_general/index.html | ||
| //! [`relay-quotas`]: ../relay_quotas/index.html |
There was a problem hiding this comment.
You likely couldn't convert these because relay doesn't depend on them directly. See rust-lang/rust#74481.
This changes the docs build to nightly, which renders intra doc links.
relay-wstringalready made use of them before, but the had not been rendered on our deployed docs.#skip-changelog