From 0b51625d138dd57ec62e0bbaa9681508d69d97df Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Thu, 15 Nov 2018 11:02:16 +0100 Subject: [PATCH] Move docs about Markdown from the Documentation section to the Markdown stdlib, fix #27094. (#30029) --- doc/src/manual/documentation.md | 391 +----------------------------- stdlib/Markdown/docs/src/index.md | 384 +++++++++++++++++++++++++++++ 2 files changed, 394 insertions(+), 381 deletions(-) diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md index 1bb2641ea2854..4f80dc4e47765 100644 --- a/doc/src/manual/documentation.md +++ b/doc/src/manual/documentation.md @@ -18,6 +18,11 @@ use indentation and code fences to delimit code examples from text. Technically, be associated with any other as metadata; Markdown happens to be the default, but one can construct other string macros and pass them to the `@doc` macro just as well. +!!! note + Markdown support is implemented in the `Markdown` standard library + and for a full list of supported syntax see the + [documentation](@ref Markdown). + Here is a more complex example, still using Markdown: ````julia @@ -96,6 +101,11 @@ As in the example above, we recommend following some simple conventions when wri (see [Code blocks](@ref)) starting with ````` ```jldoctest````` and contains any number of `julia>` prompts together with inputs and expected outputs that mimic the Julia REPL. + !!! note + Doctests are enabled by [`Documenter.jl`](https://github.com/JuliaDocs/Documenter.jl). + For more detailed documentation see Documenter's + [manual](https://juliadocs.github.io/Documenter.jl/). + For example in the following docstring a variable `a` is defined and the expected result, as printed in a Julia REPL, appears afterwards: @@ -545,384 +555,3 @@ should serve as an example of how to use `@__doc__` correctly. ```@docs Core.@__doc__ ``` - -## Markdown syntax - -The following markdown syntax is supported in Julia. - -### Inline elements - -Here "inline" refers to elements that can be found within blocks of text, i.e. paragraphs. These -include the following elements. - -#### Bold - -Surround words with two asterisks, `**`, to display the enclosed text in boldface. - -``` -A paragraph containing a **bold** word. -``` - -#### Italics - -Surround words with one asterisk, `*`, to display the enclosed text in italics. - -``` -A paragraph containing an *emphasized* word. -``` - -#### Literals - -Surround text that should be displayed exactly as written with single backticks, ``` ` ``` . - -``` -A paragraph containing a `literal` word. -``` - -Literals should be used when writing text that refers to names of variables, functions, or other -parts of a Julia program. - -!!! tip - To include a backtick character within literal text use three backticks rather than one to enclose - the text. - - ``` - A paragraph containing a ``` `backtick` character ```. - ``` - - By extension any odd number of backticks may be used to enclose a lesser number of backticks. - -#### ``\LaTeX`` - -Surround text that should be displayed as mathematics using ``\LaTeX`` syntax with double backticks, -``` `` ``` . - -``` -A paragraph containing some ``\LaTeX`` markup. -``` - -!!! tip - As with literals in the previous section, if literal backticks need to be written within double - backticks use an even number greater than two. Note that if a single literal backtick needs to - be included within ``\LaTeX`` markup then two enclosing backticks is sufficient. - -!!! note - The `\` character should be escaped appropriately if the text is embedded in a Julia source code, - for example, ``` "``\\LaTeX`` syntax in a docstring." ```, since it is interpreted as a string - literal. - -#### Links - -Links to either external or internal addresses can be written using the following syntax, where -the text enclosed in square brackets, `[ ]`, is the name of the link and the text enclosed in -parentheses, `( )`, is the URL. - -``` -A paragraph containing a link to [Julia](http://www.julialang.org). -``` - -It's also possible to add cross-references to other documented functions/methods/variables within -the Julia documentation itself. For example: - -```julia -""" - tryparse(type, str; base) - -Like [`parse`](@ref), but returns either a value of the requested type, -or [`nothing`](@ref) if the string does not contain a valid number. -""" -``` - -This will create a link in the generated docs to the [`parse`](@ref) documentation -(which has more information about what this function actually does), and to the -[`nothing`](@ref) documentation. It's good to include cross references to mutating/non-mutating -versions of a function, or to highlight a difference between two similar-seeming functions. - -!!! note - The above cross referencing is *not* a Markdown feature, and relies on - [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl), which is - used to build base Julia's documentation. - -#### Footnote references - -Named and numbered footnote references can be written using the following syntax. A footnote name -must be a single alphanumeric word containing no punctuation. - -``` -A paragraph containing a numbered footnote [^1] and a named one [^named]. -``` - -!!! note - The text associated with a footnote can be written anywhere within the same page as the footnote - reference. The syntax used to define the footnote text is discussed in the [Footnotes](@ref) section - below. - -### Toplevel elements - -The following elements can be written either at the "toplevel" of a document or within another -"toplevel" element. - -#### Paragraphs - -A paragraph is a block of plain text, possibly containing any number of inline elements defined -in the [Inline elements](@ref) section above, with one or more blank lines above and below it. - -``` -This is a paragraph. - -And this is *another* one containing some emphasized text. -A new line, but still part of the same paragraph. -``` - -#### Headers - -A document can be split up into different sections using headers. Headers use the following syntax: - -```julia -# Level One -## Level Two -### Level Three -#### Level Four -##### Level Five -###### Level Six -``` - -A header line can contain any inline syntax in the same way as a paragraph can. - -!!! tip - Try to avoid using too many levels of header within a single document. A heavily nested document - may be indicative of a need to restructure it or split it into several pages covering separate - topics. - -#### Code blocks - -Source code can be displayed as a literal block using an indent of four spaces as shown in the -following example. - -``` -This is a paragraph. - - function func(x) - # ... - end - -Another paragraph. -``` - -Additionally, code blocks can be enclosed using triple backticks with an optional "language" to -specify how a block of code should be highlighted. - -```` -A code block without a "language": - -``` -function func(x) - # ... -end -``` - -and another one with the "language" specified as `julia`: - -```julia -function func(x) - # ... -end -``` -```` - -!!! note - "Fenced" code blocks, as shown in the last example, should be preferred over indented code blocks - since there is no way to specify what language an indented code block is written in. - -#### Block quotes - -Text from external sources, such as quotations from books or websites, can be quoted using `>` -characters prepended to each line of the quote as follows. - -``` -Here's a quote: - -> Julia is a high-level, high-performance dynamic programming language for -> technical computing, with syntax that is familiar to users of other -> technical computing environments. -``` - -Note that a single space must appear after the `>` character on each line. Quoted blocks may themselves -contain other toplevel or inline elements. - -#### Images - -The syntax for images is similar to the link syntax mentioned above. Prepending a `!` character -to a link will display an image from the specified URL rather than a link to it. - -```julia -![alternative text](link/to/image.png) -``` - -#### Lists - -Unordered lists can be written by prepending each item in a list with either `*`, `+`, or `-`. - -``` -A list of items: - - * item one - * item two - * item three -``` - -Note the two spaces before each `*` and the single space after each one. - -Lists can contain other nested toplevel elements such as lists, code blocks, or quoteblocks. A -blank line should be left between each list item when including any toplevel elements within a -list. - -``` -Another list: - - * item one - - * item two - - ``` - f(x) = x - ``` - - * And a sublist: - - + sub-item one - + sub-item two -``` - -!!! note - The contents of each item in the list must line up with the first line of the item. In the above - example the fenced code block must be indented by four spaces to align with the `i` in `item two`. - -Ordered lists are written by replacing the "bullet" character, either `*`, `+`, or `-`, with a -positive integer followed by either `.` or `)`. - -``` -Two ordered lists: - - 1. item one - 2. item two - 3. item three - - 5) item five - 6) item six - 7) item seven -``` - -An ordered list may start from a number other than one, as in the second list of the above example, -where it is numbered from five. As with unordered lists, ordered lists can contain nested toplevel -elements. - -#### Display equations - -Large ``\LaTeX`` equations that do not fit inline within a paragraph may be written as display -equations using a fenced code block with the "language" `math` as in the example below. - -````julia -```math -f(a) = \frac{1}{2\pi}\int_{0}^{2\pi} (\alpha+R\cos(\theta))d\theta -``` -```` - -#### Footnotes - -This syntax is paired with the inline syntax for [Footnote references](@ref). Make sure to read -that section as well. - -Footnote text is defined using the following syntax, which is similar to footnote reference syntax, -aside from the `:` character that is appended to the footnote label. - -``` -[^1]: Numbered footnote text. - -[^note]: - - Named footnote text containing several toplevel elements. - - * item one - * item two - * item three - - ```julia - function func(x) - # ... - end - ``` -``` - -!!! note - No checks are done during parsing to make sure that all footnote references have matching footnotes. - -#### Horizontal rules - -The equivalent of an `
` HTML tag can be written using the following syntax: - -``` -Text above the line. - ---- - -And text below the line. -``` - -#### Tables - -Basic tables can be written using the syntax described below. Note that markdown tables have limited -features and cannot contain nested toplevel elements unlike other elements discussed above – -only inline elements are allowed. Tables must always contain a header row with column names. Cells -cannot span multiple rows or columns of the table. - -``` -| Column One | Column Two | Column Three | -|:---------- | ---------- |:------------:| -| Row `1` | Column `2` | | -| *Row* 2 | **Row** 2 | Column ``3`` | -``` - -!!! note - As illustrated in the above example each column of `|` characters must be aligned vertically. - - A `:` character on either end of a column's header separator (the row containing `-` characters) - specifies whether the row is left-aligned, right-aligned, or (when `:` appears on both ends) center-aligned. - Providing no `:` characters will default to right-aligning the column. - -#### Admonitions - -Specially formatted blocks, known as admonitions, can be used to highlight particular remarks. -They can be defined using the following `!!!` syntax: - -``` -!!! note - - This is the content of the note. - -!!! warning "Beware!" - - And this is another one. - - This warning admonition has a custom title: `"Beware!"`. -``` - -The type of the admonition can be any word, but some types produce special styling, -namely (in order of decreasing severity): `danger`, `warning`, `info`/`note`, and `tip`. - -A custom title for the box can be provided as a string (in double quotes) after the admonition type. -If no title text is specified after the admonition type, then the title used will be the type of the block, -i.e. `"Note"` in the case of the `note` admonition. - -Admonitions, like most other toplevel elements, can contain other toplevel elements. - -## Markdown Syntax Extensions - -Julia's markdown supports interpolation in a very similar way to basic string literals, with the -difference that it will store the object itself in the Markdown tree (as opposed to converting -it to a string). When the Markdown content is rendered the usual `show` methods will be called, -and these can be overridden as usual. This design allows the Markdown to be extended with arbitrarily -complex features (such as references) without cluttering the basic syntax. - -In principle, the Markdown parser itself can also be arbitrarily extended by packages, or an entirely -custom flavour of Markdown can be used, but this should generally be unnecessary. diff --git a/stdlib/Markdown/docs/src/index.md b/stdlib/Markdown/docs/src/index.md index 7d82df342b1fa..75acc6dc080d5 100644 --- a/stdlib/Markdown/docs/src/index.md +++ b/stdlib/Markdown/docs/src/index.md @@ -1 +1,385 @@ # Markdown + +This section describes Julia's markdown syntax, which is enabled by the +Markdown standard library. The following Markdown elements are supported: + +## Inline elements + +Here "inline" refers to elements that can be found within blocks of text, i.e. paragraphs. These +include the following elements. + +### Bold + +Surround words with two asterisks, `**`, to display the enclosed text in boldface. + +``` +A paragraph containing a **bold** word. +``` + +### Italics + +Surround words with one asterisk, `*`, to display the enclosed text in italics. + +``` +A paragraph containing an *emphasized* word. +``` + +### Literals + +Surround text that should be displayed exactly as written with single backticks, ``` ` ``` . + +``` +A paragraph containing a `literal` word. +``` + +Literals should be used when writing text that refers to names of variables, functions, or other +parts of a Julia program. + +!!! tip + To include a backtick character within literal text use three backticks rather than one to enclose + the text. + + ``` + A paragraph containing a ``` `backtick` character ```. + ``` + + By extension any odd number of backticks may be used to enclose a lesser number of backticks. + +### ``\LaTeX`` + +Surround text that should be displayed as mathematics using ``\LaTeX`` syntax with double backticks, +``` `` ``` . + +``` +A paragraph containing some ``\LaTeX`` markup. +``` + +!!! tip + As with literals in the previous section, if literal backticks need to be written within double + backticks use an even number greater than two. Note that if a single literal backtick needs to + be included within ``\LaTeX`` markup then two enclosing backticks is sufficient. + +!!! note + The `\` character should be escaped appropriately if the text is embedded in a Julia source code, + for example, ``` "``\\LaTeX`` syntax in a docstring." ```, since it is interpreted as a string + literal. Alternatively, in order to avoid escaping, it is possible to use the `raw` string macro + together with the `@doc` macro: + ``` + @doc raw"``\LaTeX`` syntax in a docstring." functionname + ``` + +### Links + +Links to either external or internal addresses can be written using the following syntax, where +the text enclosed in square brackets, `[ ]`, is the name of the link and the text enclosed in +parentheses, `( )`, is the URL. + +``` +A paragraph containing a link to [Julia](http://www.julialang.org). +``` + +It's also possible to add cross-references to other documented functions/methods/variables within +the Julia documentation itself. For example: + +```julia +""" + tryparse(type, str; base) + +Like [`parse`](@ref), but returns either a value of the requested type, +or [`nothing`](@ref) if the string does not contain a valid number. +""" +``` + +This will create a link in the generated docs to the [`parse`](@ref) documentation +(which has more information about what this function actually does), and to the +[`nothing`](@ref) documentation. It's good to include cross references to mutating/non-mutating +versions of a function, or to highlight a difference between two similar-seeming functions. + +!!! note + The above cross referencing is *not* a Markdown feature, and relies on + [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl), which is + used to build base Julia's documentation. + +### Footnote references + +Named and numbered footnote references can be written using the following syntax. A footnote name +must be a single alphanumeric word containing no punctuation. + +``` +A paragraph containing a numbered footnote [^1] and a named one [^named]. +``` + +!!! note + The text associated with a footnote can be written anywhere within the same page as the footnote + reference. The syntax used to define the footnote text is discussed in the [Footnotes](@ref) section + below. + +## Toplevel elements + +The following elements can be written either at the "toplevel" of a document or within another +"toplevel" element. + +### Paragraphs + +A paragraph is a block of plain text, possibly containing any number of inline elements defined +in the [Inline elements](@ref) section above, with one or more blank lines above and below it. + +``` +This is a paragraph. + +And this is *another* one containing some emphasized text. +A new line, but still part of the same paragraph. +``` + +### Headers + +A document can be split up into different sections using headers. Headers use the following syntax: + +```julia +# Level One +## Level Two +### Level Three +#### Level Four +##### Level Five +###### Level Six +``` + +A header line can contain any inline syntax in the same way as a paragraph can. + +!!! tip + Try to avoid using too many levels of header within a single document. A heavily nested document + may be indicative of a need to restructure it or split it into several pages covering separate + topics. + +### Code blocks + +Source code can be displayed as a literal block using an indent of four spaces as shown in the +following example. + +``` +This is a paragraph. + + function func(x) + # ... + end + +Another paragraph. +``` + +Additionally, code blocks can be enclosed using triple backticks with an optional "language" to +specify how a block of code should be highlighted. + +```` +A code block without a "language": + +``` +function func(x) + # ... +end +``` + +and another one with the "language" specified as `julia`: + +```julia +function func(x) + # ... +end +``` +```` + +!!! note + "Fenced" code blocks, as shown in the last example, should be preferred over indented code blocks + since there is no way to specify what language an indented code block is written in. + +### Block quotes + +Text from external sources, such as quotations from books or websites, can be quoted using `>` +characters prepended to each line of the quote as follows. + +``` +Here's a quote: + +> Julia is a high-level, high-performance dynamic programming language for +> technical computing, with syntax that is familiar to users of other +> technical computing environments. +``` + +Note that a single space must appear after the `>` character on each line. Quoted blocks may themselves +contain other toplevel or inline elements. + +### Images + +The syntax for images is similar to the link syntax mentioned above. Prepending a `!` character +to a link will display an image from the specified URL rather than a link to it. + +```julia +![alternative text](link/to/image.png) +``` + +### Lists + +Unordered lists can be written by prepending each item in a list with either `*`, `+`, or `-`. + +``` +A list of items: + + * item one + * item two + * item three +``` + +Note the two spaces before each `*` and the single space after each one. + +Lists can contain other nested toplevel elements such as lists, code blocks, or quoteblocks. A +blank line should be left between each list item when including any toplevel elements within a +list. + +``` +Another list: + + * item one + + * item two + + ``` + f(x) = x + ``` + + * And a sublist: + + + sub-item one + + sub-item two +``` + +!!! note + The contents of each item in the list must line up with the first line of the item. In the above + example the fenced code block must be indented by four spaces to align with the `i` in `item two`. + +Ordered lists are written by replacing the "bullet" character, either `*`, `+`, or `-`, with a +positive integer followed by either `.` or `)`. + +``` +Two ordered lists: + + 1. item one + 2. item two + 3. item three + + 5) item five + 6) item six + 7) item seven +``` + +An ordered list may start from a number other than one, as in the second list of the above example, +where it is numbered from five. As with unordered lists, ordered lists can contain nested toplevel +elements. + +### Display equations + +Large ``\LaTeX`` equations that do not fit inline within a paragraph may be written as display +equations using a fenced code block with the "language" `math` as in the example below. + +````julia +```math +f(a) = \frac{1}{2\pi}\int_{0}^{2\pi} (\alpha+R\cos(\theta))d\theta +``` +```` + +### Footnotes + +This syntax is paired with the inline syntax for [Footnote references](@ref). Make sure to read +that section as well. + +Footnote text is defined using the following syntax, which is similar to footnote reference syntax, +aside from the `:` character that is appended to the footnote label. + +``` +[^1]: Numbered footnote text. + +[^note]: + + Named footnote text containing several toplevel elements. + + * item one + * item two + * item three + + ```julia + function func(x) + # ... + end + ``` +``` + +!!! note + No checks are done during parsing to make sure that all footnote references have matching footnotes. + +### Horizontal rules + +The equivalent of an `
` HTML tag can be written using the following syntax: + +``` +Text above the line. + +--- + +And text below the line. +``` + +### Tables + +Basic tables can be written using the syntax described below. Note that markdown tables have limited +features and cannot contain nested toplevel elements unlike other elements discussed above – +only inline elements are allowed. Tables must always contain a header row with column names. Cells +cannot span multiple rows or columns of the table. + +``` +| Column One | Column Two | Column Three | +|:---------- | ---------- |:------------:| +| Row `1` | Column `2` | | +| *Row* 2 | **Row** 2 | Column ``3`` | +``` + +!!! note + As illustrated in the above example each column of `|` characters must be aligned vertically. + + A `:` character on either end of a column's header separator (the row containing `-` characters) + specifies whether the row is left-aligned, right-aligned, or (when `:` appears on both ends) center-aligned. + Providing no `:` characters will default to right-aligning the column. + +### Admonitions + +Specially formatted blocks, known as admonitions, can be used to highlight particular remarks. +They can be defined using the following `!!!` syntax: + +``` +!!! note + + This is the content of the note. + +!!! warning "Beware!" + + And this is another one. + + This warning admonition has a custom title: `"Beware!"`. +``` + +The type of the admonition can be any word, but some types produce special styling, +namely (in order of decreasing severity): `danger`, `warning`, `info`/`note`, and `tip`. + +A custom title for the box can be provided as a string (in double quotes) after the admonition type. +If no title text is specified after the admonition type, then the title used will be the type of the block, +i.e. `"Note"` in the case of the `note` admonition. + +Admonitions, like most other toplevel elements, can contain other toplevel elements. + +## Markdown Syntax Extensions + +Julia's markdown supports interpolation in a very similar way to basic string literals, with the +difference that it will store the object itself in the Markdown tree (as opposed to converting +it to a string). When the Markdown content is rendered the usual `show` methods will be called, +and these can be overridden as usual. This design allows the Markdown to be extended with arbitrarily +complex features (such as references) without cluttering the basic syntax. + +In principle, the Markdown parser itself can also be arbitrarily extended by packages, or an entirely +custom flavour of Markdown can be used, but this should generally be unnecessary.