# When adding `x` and `y` together we obtain a new rational number:
z = x + y</code></pre><p>In the lines starting with <code>#</code> we can use regular markdown syntax, for example the <code>#</code> used for the heading and the backticks for formatting code. The other lines are regular julia code. We note a couple of things:</p><ul><li>The script is valid julia, which means that we can <code>include</code> it and the example will run (for example in the <code>test/runtests.jl</code> script, to include the example in the test suite).</li><li>The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.</li></ul><p>For simple use this is all you need to know. The following additional special syntax can also be used:</p><ul><li><code>#md</code>, <code>#nb</code>, <code>#jl</code>, <code>#src</code>: tags to filter lines, see <ahref="#Filtering-Lines-1">Filtering Lines</a>,</li><li><code>#-</code>: tag to manually control chunk-splits, see <ahref="../pipeline/#Custom-control-over-chunk-splits-1">Custom control over chunk splits</a>.</li></ul><p>There is also some default convenience replacements that will always be performed, see <ahref="#Default-Replacements-1">Default Replacements</a>.</p><h2><aclass="nav-anchor"id="Filtering-Lines-1"href="#Filtering-Lines-1"><strong>2.2.</strong> Filtering Lines</a></h2><p>It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:</p><ul><li><code>#md</code>: line exclusive to markdown output,</li><li><code>#nb</code>: line exclusive to notebook output,</li><li><code>#jl</code>: line exclusive to script output,</li><li><code>#src</code>: line exclusive to the source code and thus filtered out unconditionally.</li></ul><p>Lines <em>starting</em> with one of these tokens are filtered out in the <ahref="../pipeline/#Pre-processing-1">preprocessing step</a>.</p><p>Suppose, for example, that we want to include a docstring within a <code>@docs</code> block using Documenter. Obviously we don't want to include this in the notebook, since <code>@docs</code> is Documenter syntax that the notebook will not understand. This is a case where we can prepend <code>#md</code> to those lines:</p><pre><codeclass="language-julia">#md # ```@docs
z = x + y</code></pre><p>In the lines starting with <code>#</code> we can use regular markdown syntax, for example the <code>#</code> used for the heading and the backticks for formatting code. The other lines are regular julia code. We note a couple of things:</p><ul><li>The script is valid julia, which means that we can <code>include</code> it and the example will run (for example in the <code>test/runtests.jl</code> script, to include the example in the test suite).</li><li>The script is "self-explanatory", i.e. the markdown lines works as comments and thus serve as good documentation on its own.</li></ul><p>For simple use this is all you need to know. The following additional special syntax can also be used:</p><ul><li><code>#md</code>, <code>#nb</code>, <code>#jl</code>, <code>#src</code>: tags to filter lines, see <ahref="#Filtering-Lines-1">Filtering Lines</a>,</li><li><code>#-</code> (<code>#+</code>): tag to manually control chunk-splits, see <ahref="../pipeline/#Custom-control-over-chunk-splits-1">Custom control over chunk splits</a>.</li></ul><p>There is also some default convenience replacements that will always be performed, see <ahref="#Default-Replacements-1">Default Replacements</a>.</p><h2><aclass="nav-anchor"id="Filtering-Lines-1"href="#Filtering-Lines-1"><strong>2.2.</strong> Filtering Lines</a></h2><p>It is often useful to filter out lines in the source depending on the output format. For this purpose there are a number of "tokens" that can be used to mark the purpose of certain lines:</p><ul><li><code>#md</code>: line exclusive to markdown output,</li><li><code>#nb</code>: line exclusive to notebook output,</li><li><code>#jl</code>: line exclusive to script output,</li><li><code>#src</code>: line exclusive to the source code and thus filtered out unconditionally.</li></ul><p>Lines <em>starting</em> with one of these tokens are filtered out in the <ahref="../pipeline/#Pre-processing-1">preprocessing step</a>.</p><p>Suppose, for example, that we want to include a docstring within a <code>@docs</code> block using Documenter. Obviously we don't want to include this in the notebook, since <code>@docs</code> is Documenter syntax that the notebook will not understand. This is a case where we can prepend <code>#md</code> to those lines:</p><pre><codeclass="language-julia">#md # ```@docs
@ -26,4 +26,4 @@ Lets define two rational numbers, `x` and `y`:</code></pre><p>Chunk #2:</p><pre>
@@ -26,4 +26,4 @@ Lets define two rational numbers, `x` and `y`:</code></pre><p>Chunk #2:</p><pre>
y = 2 // 5</code></pre><p>Chunk #3:</p><pre><codeclass="language-markdown">When adding `x` and `y` together we obtain a new rational number:</code></pre><p>Chunk #4:</p><pre><codeclass="language-julia">z = x + y</code></pre><p>It is then up to the <ahref="#Document-generation-1">Document generation</a> step to decide how these chunks should be treated.</p><h3><aclass="nav-anchor"id="Custom-control-over-chunk-splits-1"href="#Custom-control-over-chunk-splits-1">Custom control over chunk splits</a></h3><p>Sometimes it is convenient to be able to manually control how the chunks are split. For example, if you want to split a block of code into two, such that they end up in two different <code>@example</code> blocks or notebook cells. The <code>#-</code> token can be used for this purpose. All lines starting with <code>#-</code> are used as "chunk-splitters":</p><pre><codeclass="language-julia">x = 1 // 3
y = 2 // 5
#-
z = x + y</code></pre><p>The example above would result in two consecutive code-chunks.</p><divclass="admonition tip"><divclass="admonition-title">Tip</div><divclass="admonition-text"><p>The rest of the line, after <code>#-</code>, is discarded, so it is possible to use e.g. <code>#-------------</code> as a chunk splitter, which may make the source code more readable.</p></div></div><h2><aclass="nav-anchor"id="Document-generation-1"href="#Document-generation-1"><strong>3.3.</strong> Document generation</a></h2><p>After the parsing it is time to generate the output. What is done in this step is very different depending on the output target, and it is describe in more detail in the Output format sections: <ahref="../outputformats/#Markdown-Output-1">Markdown Output</a>, <ahref="../outputformats/#Notebook-Output-1">Notebook Output</a> and <ahref="../outputformats/#Script-Output-1">Script Output</a>. Using the default settings, the following is happening:</p><ul><li>Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to <code>@example</code>-blocks),</li><li>Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,</li><li>Script output: markdown chunks are discarded, code chunks are printed as-is.</li></ul><h2><aclass="nav-anchor"id="Post-processing-1"href="#Post-processing-1"><strong>3.4.</strong> Post-processing</a></h2><p>When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See <ahref="../customprocessing/#Custom-pre-and-post-processing-1">Custom pre- and post-processing</a>.</p><h2><aclass="nav-anchor"id="Writing-to-file-1"href="#Writing-to-file-1"><strong>3.5.</strong> Writing to file</a></h2><p>The last step of the generation is writing to file. The result is written to <code>$(outputdir)/$(name)(.md|.ipynb|.jl)</code> where <code>outputdir</code> is the output directory supplied by the user (for example <code>docs/generated</code>), and <code>name</code> is a user supplied filename. It is recommended to add the output directory to <code>.gitignore</code> since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.</p><footer><hr/><aclass="previous"href="../fileformat/"><spanclass="direction">Previous</span><spanclass="title"><strong>2.</strong> File Format</span></a><aclass="next"href="../outputformats/"><spanclass="direction">Next</span><spanclass="title"><strong>4.</strong> Output Formats</span></a></footer></article></body></html>
z = x + y</code></pre><p>The example above would result in two consecutive code-chunks.</p><divclass="admonition tip"><divclass="admonition-title">Tip</div><divclass="admonition-text"><p>The rest of the line, after <code>#-</code>, is discarded, so it is possible to use e.g. <code>#-------------</code> as a chunk splitter, which may make the source code more readable.</p></div></div><p>It is also possible to use <code>#+</code> as a chunk splitter. The difference between <code>#+</code> and <code>#-</code> is that <code>#+</code> enables Documenter's "continued"-blocks, see the <ahref="https://juliadocs.github.io/Documenter.jl/stable/">Documenter manual</a>.</p><h2><aclass="nav-anchor"id="Document-generation-1"href="#Document-generation-1"><strong>3.3.</strong> Document generation</a></h2><p>After the parsing it is time to generate the output. What is done in this step is very different depending on the output target, and it is describe in more detail in the Output format sections: <ahref="../outputformats/#Markdown-Output-1">Markdown Output</a>, <ahref="../outputformats/#Notebook-Output-1">Notebook Output</a> and <ahref="../outputformats/#Script-Output-1">Script Output</a>. Using the default settings, the following is happening:</p><ul><li>Markdown output: markdown chunks are printed as-is, code chunks are put inside a code fence (defaults to <code>@example</code>-blocks),</li><li>Notebook output: markdown chunks are printed in markdown cells, code chunks are put in code cells,</li><li>Script output: markdown chunks are discarded, code chunks are printed as-is.</li></ul><h2><aclass="nav-anchor"id="Post-processing-1"href="#Post-processing-1"><strong>3.4.</strong> Post-processing</a></h2><p>When the document is generated the user, again, has the option to hook-into the generation with a custom post-processing function. The reason is that one might want to change things that are only visible in the rendered document. See <ahref="../customprocessing/#Custom-pre-and-post-processing-1">Custom pre- and post-processing</a>.</p><h2><aclass="nav-anchor"id="Writing-to-file-1"href="#Writing-to-file-1"><strong>3.5.</strong> Writing to file</a></h2><p>The last step of the generation is writing to file. The result is written to <code>$(outputdir)/$(name)(.md|.ipynb|.jl)</code> where <code>outputdir</code> is the output directory supplied by the user (for example <code>docs/generated</code>), and <code>name</code> is a user supplied filename. It is recommended to add the output directory to <code>.gitignore</code> since the idea is that the generated documents will be generated as part of the build process rather than beeing files in the repo.</p><footer><hr/><aclass="previous"href="../fileformat/"><spanclass="direction">Previous</span><spanclass="title"><strong>2.</strong> File Format</span></a><aclass="next"href="../outputformats/"><spanclass="direction">Next</span><spanclass="title"><strong>4.</strong> Output Formats</span></a></footer></article></body></html>
zeptodoctor
6 years ago