mirror of
https://github.com/ilyakooo0/nixpkgs.git
synced 2024-08-16 18:50:49 +03:00
doc: Update manuals bespoke syntax
doc: add figure definition to bespoke syntax reference doc: add example definition to bespoke syntax reference doc: add footnote definition to beskpoke syntax reference The usage of footnotes in the manuals is not the one documented in markdown-it-py: https://python-markdown.github.io/extensions/footnotes/ doc: add inline comment definition to beskpoke syntax reference doc: add typographic replacements to beskpoke syntax reference doc: Fix rendering of bespoke syntax reference doc: remove references to DocBook in the NixOS manual doc: add entry on lack of HTML support doc: Minor improvement doc: update typographic replacements entry in beskpoke syntax reference doc: add link reference definitions to beskpoke syntax reference doc: fix footnote definition in beskpoke syntax reference doc: Minor improvements from code review Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io> Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
This commit is contained in:
parent
b23ce8c1ed
commit
a63b9c15c9
@ -71,6 +71,11 @@ If you **omit a link text** for a link pointing to a section, the text will be s
|
||||
|
||||
This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing).
|
||||
|
||||
|
||||
#### HTML
|
||||
|
||||
Inlining HTML is not allowed. Parts of the documentation gets rendered to various non-HTML formats, such as man pages in the case of NixOS manual.
|
||||
|
||||
#### Roles
|
||||
|
||||
If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``. The references will turn into links when a mapping exists in [`doc/manpage-urls.json`](./manpage-urls.json).
|
||||
@ -265,6 +270,79 @@ You, as the writer of documentation, are still in charge of its content.
|
||||
_Default:_ the output path's hash.
|
||||
```
|
||||
|
||||
#### Examples
|
||||
|
||||
To define a referenceable figure use the following fencing:
|
||||
|
||||
```markdown
|
||||
:::{.example #an-attribute-set-example}
|
||||
# An attribute set example
|
||||
|
||||
You can add text before
|
||||
|
||||
```nix
|
||||
{ a = 1; b = 2;}
|
||||
```
|
||||
|
||||
and after code fencing
|
||||
:::
|
||||
```
|
||||
|
||||
Defining examples through the `example` fencing class adds them to a "List of Examples" section after the Table of Contents.
|
||||
Though this is not shown in the rendered documentation on nixos.org.
|
||||
|
||||
#### Figures
|
||||
|
||||
To define a referencable figure use the following fencing:
|
||||
|
||||
```markdown
|
||||
::: {.figure #nixos-logo}
|
||||
# NixOS Logo
|
||||
![NixOS logo](./nixos_logo.png)
|
||||
:::
|
||||
```
|
||||
|
||||
Defining figures through the `figure` fencing class adds them to a `List of Figures` after the `Table of Contents`.
|
||||
Though this is not shown in the rendered documentation on nixos.org.
|
||||
|
||||
#### Footnotes
|
||||
|
||||
To add a foonote explanation, use the following syntax:
|
||||
|
||||
```markdown
|
||||
Sometimes it's better to add context [^context] in a footnote.
|
||||
|
||||
[^context]: This explanation will be rendered at the end of the chapter.
|
||||
```
|
||||
|
||||
#### Inline comments
|
||||
|
||||
Inline comments are supported with following syntax:
|
||||
|
||||
```markdown
|
||||
<!-- This is an inline comment -->
|
||||
```
|
||||
|
||||
The comments will not be rendered in the rendered HTML.
|
||||
|
||||
#### Link reference definitions
|
||||
|
||||
Links can reference a label, for example, to make the link target reusable:
|
||||
|
||||
```markdown
|
||||
::: {.note}
|
||||
Reference links can also be used to [shorten URLs][url-id] and keep the markdown readable.
|
||||
:::
|
||||
|
||||
[url-id]: https://github.com/NixOS/nixpkgs/blob/19d4f7dc485f74109bd66ef74231285ff797a823/doc/README.md
|
||||
```
|
||||
|
||||
This syntax is taken from [CommonMark](https://spec.commonmark.org/0.30/#link-reference-definitions).
|
||||
|
||||
#### Typographic replacements
|
||||
|
||||
Typographic replacements are enabled. Check the [list of possible replacement patterns check](https://github.com/executablebooks/markdown-it-py/blob/3613e8016ecafe21709471ee0032a90a4157c2d1/markdown_it/rules_core/replacements.py#L1-L15).
|
||||
|
||||
## Getting help
|
||||
|
||||
If you need documentation-specific help or reviews, ping [@NixOS/documentation-reviewers](https://github.com/orgs/nixos/teams/documentation-reviewers) on your pull request.
|
||||
|
@ -1,6 +1,6 @@
|
||||
# Contributing to this manual {#chap-contributing}
|
||||
|
||||
The [DocBook] and CommonMark sources of the NixOS manual are in the [nixos/doc/manual](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual) subdirectory of the [Nixpkgs](https://github.com/NixOS/nixpkgs) repository.
|
||||
The sources of the NixOS manual are in the [nixos/doc/manual](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual) subdirectory of the [Nixpkgs](https://github.com/NixOS/nixpkgs) repository.
|
||||
This manual uses the [Nixpkgs manual syntax](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup).
|
||||
|
||||
You can quickly check your edits with the following:
|
||||
|
@ -7,7 +7,7 @@ worthy contribution to the project.
|
||||
|
||||
## Building the Manual {#sec-writing-docs-building-the-manual}
|
||||
|
||||
The DocBook sources of the [](#book-nixos-manual) are in the
|
||||
The sources of the [](#book-nixos-manual) are in the
|
||||
[`nixos/doc/manual`](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual)
|
||||
subdirectory of the Nixpkgs repository.
|
||||
|
||||
@ -29,65 +29,3 @@ nix-build nixos/release.nix -A manual.x86_64-linux
|
||||
When this command successfully finishes, it will tell you where the
|
||||
manual got generated. The HTML will be accessible through the `result`
|
||||
symlink at `./result/share/doc/nixos/index.html`.
|
||||
|
||||
## Editing DocBook XML {#sec-writing-docs-editing-docbook-xml}
|
||||
|
||||
For general information on how to write in DocBook, see [DocBook 5: The
|
||||
Definitive Guide](https://tdg.docbook.org/tdg/5.1/).
|
||||
|
||||
Emacs nXML Mode is very helpful for editing DocBook XML because it
|
||||
validates the document as you write, and precisely locates errors. To
|
||||
use it, see [](#sec-emacs-docbook-xml).
|
||||
|
||||
[Pandoc](https://pandoc.org/) can generate DocBook XML from a multitude of
|
||||
formats, which makes a good starting point. Here is an example of Pandoc
|
||||
invocation to convert GitHub-Flavoured MarkDown to DocBook 5 XML:
|
||||
|
||||
```ShellSession
|
||||
pandoc -f markdown_github -t docbook5 docs.md -o my-section.md
|
||||
```
|
||||
|
||||
Pandoc can also quickly convert a single `section.xml` to HTML, which is
|
||||
helpful when drafting.
|
||||
|
||||
Sometimes writing valid DocBook is too difficult. In this case,
|
||||
submit your documentation updates in a [GitHub
|
||||
Issue](https://github.com/NixOS/nixpkgs/issues/new) and someone will
|
||||
handle the conversion to XML for you.
|
||||
|
||||
## Creating a Topic {#sec-writing-docs-creating-a-topic}
|
||||
|
||||
You can use an existing topic as a basis for the new topic or create a
|
||||
topic from scratch.
|
||||
|
||||
Keep the following guidelines in mind when you create and add a topic:
|
||||
|
||||
- The NixOS [`book`](https://tdg.docbook.org/tdg/5.0/book.html)
|
||||
element is in `nixos/doc/manual/manual.xml`. It includes several
|
||||
[`parts`](https://tdg.docbook.org/tdg/5.0/book.html) which are in
|
||||
subdirectories.
|
||||
|
||||
- Store the topic file in the same directory as the `part` to which it
|
||||
belongs. If your topic is about configuring a NixOS module, then the
|
||||
XML file can be stored alongside the module definition `nix` file.
|
||||
|
||||
- If you include multiple words in the file name, separate the words
|
||||
with a dash. For example: `ipv6-config.xml`.
|
||||
|
||||
- Make sure that the `xml:id` value is unique. You can use abbreviations
|
||||
if the ID is too long. For example: `nixos-config`.
|
||||
|
||||
- Determine whether your topic is a chapter or a section. If you are
|
||||
unsure, open an existing topic file and check whether the main
|
||||
element is chapter or section.
|
||||
|
||||
## Adding a Topic to the Book {#sec-writing-docs-adding-a-topic}
|
||||
|
||||
Open the parent CommonMark file and add a line to the list of
|
||||
chapters with the file name of the topic that you created. If you
|
||||
created a `section`, you add the file to the `chapter` file. If you created
|
||||
a `chapter`, you add the file to the `part` file.
|
||||
|
||||
If the topic is about configuring a NixOS module, it can be
|
||||
automatically included in the manual by using the `meta.doc` attribute.
|
||||
See [](#sec-meta-attributes) for an explanation.
|
||||
|
Loading…
Reference in New Issue
Block a user