|
54 | 54 | //! > high level tutorial. They should be explained in the rust-doc of the corresponding type or |
55 | 55 | //! > macro. |
56 | 56 | //! |
57 | | -//! 2. 🧘 Less is More: For reasons mentioned [above](#crate::why-rust-docs), the more concise this |
58 | | -//! crate is, the better. |
| 57 | +//! 2. 🧘 Less is More: For reasons mentioned [above](#why-rust-docs), the more concise this crate |
| 58 | +//! is, the better. |
59 | 59 | //! 3. √ Don’t Repeat Yourself – DRY: A summary of the above two points. Authors should always |
60 | 60 | //! strive to avoid any duplicate information. Every concept should ideally be documented in |
61 | 61 | //! *ONE* place and one place only. This makes the task of maintaining topics significantly |
|
69 | 69 | //! > what topics are already covered in this crate, and how you can build on top of the information |
70 | 70 | //! > that they already pose, rather than repeating yourself**. |
71 | 71 | //! |
72 | | -//! For more details about documenting guidelines, see: |
73 | | -//! <https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/DOCUMENTATION_GUIDELINES.md#L23> |
| 72 | +//! For more details see the [latest documenting guidelines](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/DOCUMENTATION_GUIDELINES.md). |
74 | 73 | //! |
75 | 74 | //! #### Example: Explaining `#[pallet::call]` |
76 | 75 | //! |
|
133 | 132 | //! compromise, but in the long term, we should work towards finding a way to maintain different |
134 | 133 | //! revisions of this crate. |
135 | 134 | //! |
136 | | -//! ## How to Build |
| 135 | +//! ## How to Develop Locally |
137 | 136 | //! |
138 | | -//! To build this crate properly, with with right HTML headers injected, run: |
| 137 | +//! To view the docs specific [`crate`] locally for development, including the correct HTML headers |
| 138 | +//! injected, run: |
139 | 139 | //! |
140 | | -//! ```no_compile |
141 | | -//! RUSTDOCFLAGS="--html-in-header $(pwd)/docs/sdk/headers/toc.html" cargo doc -p polkadot-sdk-docs |
| 140 | +//! ```sh |
| 141 | +//! SKIP_WASM_BUILD=1 RUSTDOCFLAGS="--html-in-header $(pwd)/docs/sdk/headers/toc.html" cargo doc -p polkadot-sdk-docs --no-deps --open |
142 | 142 | //! ``` |
143 | 143 | //! |
144 | | -//! adding `--no-deps` would speed up the process while development. If even faster build time for |
145 | | -//! docs is needed, you can temporarily remove most of the substrate/cumulus dependencies that are |
146 | | -//! only used for linking purposes. |
| 144 | +//! If even faster build time for docs is needed, you can temporarily remove most of the |
| 145 | +//! substrate/cumulus dependencies that are only used for linking purposes. |
| 146 | +//! |
| 147 | +//! For more on local development, see [`crate::reference_docs::development_environment_advice`]. |
0 commit comments