<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>src/doc/README.md - fork/cargo @ 0.90.0</title>
<meta name="description" content="src/doc/README.md in fork/cargo at 0.90.0.">
<meta property="og:title" content="src/doc/README.md - fork/cargo @ 0.90.0">
<meta property="og:description" content="src/doc/README.md in fork/cargo at 0.90.0.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="0.90.0" data-tip="c24e1064277fe51ab72011e2612e556ac56addf7">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/cargo</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/cargo</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">bors</span><span class="commit-message" data-commit="26b73d15a68fb94579f6d3590585ec0e9d81d3d5">Auto merge of #12117 - ehuss:semver-check-doc, r=weihanglo</span><span class="snapshot-sha sha" data-commit="26b73d15a68fb94579f6d3590585ec0e9d81d3d5">26b73d15a</span><time datetime="2023-05-09T20:28:03+00:00" title="2023-05-09 20:28:03 +0000">2023-05-09</time></p>
<header class="topbar"><details class="switcher"><summary>0.90.0</summary><div class="menu"><strong>branches</strong><a href="/fork/cargo/ref/master/">master</a><strong>tags</strong><a href="/fork/cargo/ref/0.87.0/">0.87.0</a><a href="/fork/cargo/ref/0.88.0/">0.88.0</a><a href="/fork/cargo/ref/0.89.0/">0.89.0</a><a class="current" href="/fork/cargo/ref/0.90.0/">0.90.0</a><a href="/fork/cargo/ref/0.91.0/">0.91.0</a><a href="/fork/cargo/ref/0.92.0/">0.92.0</a><a href="/fork/cargo/ref/0.93.0/">0.93.0</a><a href="/fork/cargo/ref/home-0.5.12/">home-0.5.12</a><a class="all" href="/fork/cargo/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/cargo/">cargo</a> / <a href="/fork/cargo/ref/0.90.0/tree/src/">src</a> / <a href="/fork/cargo/ref/0.90.0/tree/src/doc/">doc</a> / <span class="cur">README.md</span></nav>
<span class="view-stats"><span>2.4 KiB</span><span>71 lines</span></span><span class="actions"><a class="raw" href="/fork/cargo/raw/d67838868525cf150fb038b3e42bad85494ce3f3/src/doc/README.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>Cargo documentation</h1>
<p>This directory contains Cargo's documentation. There are two parts, <a href="https://doc.rust-lang.org/cargo/">The Cargo
Book</a> which is built with <a href="https://github.com/rust-lang/mdBook">mdbook</a> and the man pages, which are built with
<a href="https://github.com/rust-lang/cargo/tree/master/crates/mdman/">mdman</a>.</p>
<h3>Building the book</h3>
<p>Building the book requires <a href="https://github.com/rust-lang/mdBook">mdBook</a>. To get it:</p>
<pre class="language-bash"><a-o>$</a-o><a-f> </a-f><a-pr>cargo</a-pr> install mdbook</pre>
<p>To build the book:</p>
<pre class="language-bash"><a-o>$</a-o><a-f> </a-f><a-pr>mdbook</a-pr> build</pre>
<p><code>mdbook</code> provides a variety of different commands and options to help you work
on the book:</p>
<ul>
<li><code>mdbook build --open</code>: Build the book and open it in a web browser.</li>
<li><code>mdbook serve</code>: Launches a web server on localhost. It also automatically
rebuilds the book whenever any file changes and automatically reloads your
web browser.</li>
</ul>
<p>The book contents are driven by the <a href="/fork/cargo/ref/0.90.0/blob/src/doc/src/SUMMARY.md"><code>SUMMARY.md</code></a> file, and
every file must be linked there.</p>
<h3>Building the man pages</h3>
<p>The man pages use a tool called <a href="https://github.com/rust-lang/cargo/tree/master/crates/mdman/">mdman</a> to convert markdown to a man page
format. Check out the documentation at
<a href="/fork/cargo/ref/0.90.0/tree/crates/mdman/doc/"><code>mdman/doc/</code></a>
for more details.</p>
<p>The man pages are converted from a templated markdown (located in the
<a href="/fork/cargo/ref/0.90.0/tree/src/doc/man/"><code>src/doc/man/</code></a>
directory) to three different formats:</p>
<ol>
<li>Troff-style man pages, saved in <a href="/fork/cargo/ref/0.90.0/tree/src/etc/man/"><code>src/etc/man/</code></a>.</li>
<li>Markdown (with some HTML) for the Cargo Book, saved in
<a href="/fork/cargo/ref/0.90.0/tree/src/doc/src/commands/"><code>src/doc/src/commands/</code></a>.</li>
<li>Plain text (needed for embedded man pages on platforms without man such as
Windows), saved in <a href="/fork/cargo/ref/0.90.0/tree/src/doc/man/generated_txt/"><code>src/doc/man/generated_txt/</code></a>.</li>
</ol>
<p>To rebuild the man pages, run <code>cargo build-man</code> inside the workspace.</p>
<h3>SemVer chapter tests</h3>
<p>There is a script to verify that the examples in the SemVer chapter work as
intended. To run the tests, run <code>cargo +stable run -p semver-check</code>.</p>
<p>Note that these tests run on the most recent stable release because they
validate the output of the compiler diagnostics. The output can change between
releases, so we pin to a specific release to avoid frequent and unexpected
breakage.</p>
<h2>Contributing</h2>
<p>We'd love your help with improving the documentation! Please feel free to
<a href="https://github.com/rust-lang/cargo/issues">open issues</a> about anything, and
send in PRs for things you'd like to fix or change. If your change is large,
please open an issue first, so we can make sure that it's something we'd
accept before you go through the work of getting a PR together.</p>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>#</a-p> <a-tt>Cargo documentation</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">This directory contains Cargo&#39;s documentation. There are two parts, [The Cargo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">Book] which is built with [mdbook] and the man pages, which are built with</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">[mdman].</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"><a-tu>[The Cargo Book]</a-tu>: <a-tu>https://doc.rust-lang.org/cargo/</a-tu></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"><a-tu>[mdBook]</a-tu>: <a-tu>https://github.com/rust-lang/mdBook</a-tu></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text"><a-tu>[mdman]</a-tu>: <a-tu>https://github.com/rust-lang/cargo/tree/master/crates/mdman/</a-tu></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text"><a-p>###</a-p> <a-tt>Building the book</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">Building the book requires [mdBook]. To get it:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"><a-p>```</a-p><a-tl>console</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"><a-p>$ cargo install mdbook</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"><a-p>To build the book:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"><a-p>```</a-p><a-tl>console</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"><a-p>$ mdbook build</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"><a-p>`mdbook` provides a variety of different commands and options to help you work</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"><a-p>on the book:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"><a-p>* `mdbook build --open`: Build the book and open it in a web browser.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"><a-p>* `mdbook serve`: Launches a web server on localhost. It also automatically</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"><a-p>  rebuilds the book whenever any file changes and automatically reloads your</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"><a-p>  web browser.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"><a-p>The book contents are driven by the [`SUMMARY.md`](src/SUMMARY.md) file, and</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"><a-p>every file must be linked there.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"><a-p>### </a-p><a-tt>Building the man pages</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text"><a-p>The man pages use a tool called [mdman] to convert markdown to a man page</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"><a-p>format. Check out the documentation at</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"><a-p>[`mdman/doc/`](../../crates/mdman/doc/)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"><a-p>for more details.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"><a-p>The man pages are converted from a templated markdown (located in the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"><a-p>[`src/doc/man/`](man)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"><a-p>directory) to three different formats:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"><a-p>1. Troff-style man pages, saved in [`src/etc/man/`](../etc/man).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text"><a-p>2. Markdown (with some HTML) for the Cargo Book, saved in</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"><a-p>   [`src/doc/src/commands/`](src/commands).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"><a-p>3. Plain text (needed for embedded man pages on platforms without man such as</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"><a-p>   Windows), saved in [`src/doc/man/generated_txt/`](man/generated_txt).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text"><a-p>To rebuild the man pages, run `cargo build-man` inside the workspace.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text"><a-p>### </a-p><a-tt>SemVer chapter tests</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"><a-p>There is a script to verify that the examples in the SemVer chapter work as</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"><a-p>intended. To run the tests, run `cargo +stable run -p semver-check`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"><a-p>Note that these tests run on the most recent stable release because they</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"><a-p>validate the output of the compiler diagnostics. The output can change between</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"><a-p>releases, so we pin to a specific release to avoid frequent and unexpected</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"><a-p>breakage.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"><a-p>## </a-p><a-tt>Contributing</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text">We&#39;d love your help with improving the documentation! Please feel free to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text">[open issues](https://github.com/rust-lang/cargo/issues) about anything, and</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text">send in PRs for things you&#39;d like to fix or change. If your change is large,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text">please open an issue first, so we can make sure that it&#39;s something we&#39;d</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text">accept before you go through the work of getting a PR together.</span></span></pre></div></div>
</main>
</body>
</html>
