|
|
| Line 1: |
Line 1: |
| − | == What should I work on? ==
| |
| − |
| |
| | Authoritative documentation for the Nix ecosystem is on [https://nix.dev/ nix.dev] and maintained by the [https://github.com/nixos/nix.dev/tree/master/maintainers Nix documentation team]. | | Authoritative documentation for the Nix ecosystem is on [https://nix.dev/ nix.dev] and maintained by the [https://github.com/nixos/nix.dev/tree/master/maintainers Nix documentation team]. |
| | | | |
| | See [https://nix.dev/contributing/documentation Contributing Documentation] for how you can help. | | See [https://nix.dev/contributing/documentation Contributing Documentation] for how you can help. |
| − |
| |
| − | The rest of this article contains historical notes that are not actively curated and may or may not still apply.
| |
| − |
| |
| − | == Where do I find the docs? ==
| |
| − |
| |
| − | The Nix documentation is on GitHub in the following repositories:
| |
| − |
| |
| − | * [https://github.com/NixOS/nix/tree/master/doc/manual Nix manual]
| |
| − | * [https://github.com/NixOS/nixpkgs/tree/master/doc Nixpkgs manual]
| |
| − | * [https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual NixOS manual]
| |
| − | * [https://github.com/NixOS/nixops NixOps]
| |
| − | * [https://github.com/NixOS/hydra Hydra]
| |
| − |
| |
| − | == How do I create a topic? ==
| |
| − |
| |
| − | Nix documentation uses DocBook 5, an XML markup language.
| |
| − | For a quick overview of DocBook, see [https://docbook.rocks this page].
| |
| − | For more in-depth information have a look at [https://tdg.docbook.org/tdg/5.1/ DocBook the Definitive Guide].
| |
| − |
| |
| − | 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:
| |
| − | * Make sure to store the topic file in the same directory as the book file to which you want to add the topic. The book file is an XML file normally named <tt>manual.xml</tt>.
| |
| − | * If you include multiple words in the file name, separate the words with a dash. For example: <tt>installing-cli.xml</tt>
| |
| − | * Make sure that the <code>xml:id</code> value is unique. You can use abbreviations the ID is too long. For example: <tt>nixos-config</tt>
| |
| − | * 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 <code>chapter</code> or <code>section</code>.
| |
| − |
| |
| − | ''Note: In the future you will be able to use a topic template. We welcome contributions to the template pool!''
| |
| − |
| |
| − | == How do I add a topic to a book? ==
| |
| − |
| |
| − | Open the parent XML file and add an <tt>xi:include element</tt> 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 book file.
| |
| − |
| |
| − | == How do I build and test the manual? ==
| |
| − |
| |
| − | Before you commit the new or updated content, you compile the source files and check that the generated output looks and behaves as expected. You use Nix to build the documentation, and each manual requires a slightly different process.
| |
| − |
| |
| − | === Prerequisites ===
| |
| − | Before you build and test the output, you must install Nix on the machine where you store the local Git repo of the documentation.
| |
| − |
| |
| − | === How to build the NixOS manual ===
| |
| − | # In a terminal, navigate to the <tt>/nixpkgs/nixos</tt> directory, where the <tt>doc</tt> directory is located.
| |
| − | # Run the following command: <syntaxhighlight lang="console" inline>$ nix-build release.nix -A manual.x86_64-linux</syntaxhighlight>
| |
| − | # Open the generated output in a Web browser from the following path: <tt>../nixos/result/share/doc/<project_name>/manual.html</tt>
| |
| − |
| |
| − | === How to build the Nixpkgs manual ===
| |
| − | # In a terminal, navigate to the <tt>nixpkgs/doc</tt> directory.
| |
| − | # Run the following command: <syntaxhighlight lang="console" inline>$ nix-build</syntaxhighlight>
| |
| − | # Open the generated output in a Web browser from the following path: <tt>../nixpkgs/result/share/doc/<project_name>/manual.html</tt>
| |
| − |
| |
| − | === How to build the Nix manual ===
| |
| − | In the [https://github.com/NixOS/nix Nix] repository run the following command once
| |
| − | to configure the project:
| |
| − | <syntaxhighlight lang="console">$ nix-shell --command 'autoreconf --install && ./configure --enable-doc-gen'</syntaxhighlight>
| |
| − | To build the actual documentation run the following command:
| |
| − | <syntaxhighlight lang="console">$ nix-shell --command 'make doc/manual/manual.html'</syntaxhighlight>
| |
| − | <code>doc/manual/manual.html</code> can be then opened in a browser.
| |
| − |
| |
| − | == See also ==
| |
| − |
| |
| − | * [[Docbook Editor Configuration]]
| |
| | | | |
| | [[:Category:Contributing]] | | [[:Category:Contributing]] |